# Checkbox (React Native)

> Checkboxes and groups with select-all and the mixed state.

GramproKit for React Native · Forms · Beta · Source: https://kit.gramproindia.com/native/docs/checkbox

> **Beta:** React Native support is in beta. APIs may change or break between prereleases (npm tag `native`).

_Interactive demo:_ [open the live example](https://kit.gramproindia.com/native/docs/checkbox). The example's source:

```tsx
import { useState } from "react";
import { Checkbox, CheckboxGroup } from "@/component-lib/checkbox";
import { Section } from "./layout"; // Section and Row: page layout for the demo

export function CheckboxDemo() {
  const [terms, setTerms] = useState(false);
  const [channels, setChannels] = useState<string[]>(["sms"]);
  return (
    <>
      <Section title="Checkbox · states">
        <Checkbox label="Unchecked" />
        <Checkbox label="Checked" defaultChecked />
        <Checkbox label="Indeterminate" checked="indeterminate" />
        <Checkbox label="Disabled" disabled />
        <Checkbox label="Disabled and checked" disabled defaultChecked />
        <Checkbox
          label="I accept the terms"
          description="You can withdraw at any time."
          required
          checked={terms}
          onCheckedChange={setTerms}
          error={terms ? undefined : "Accept the terms to continue."}
        />
        <Checkbox size="sm" label="Small" defaultChecked />
        <Checkbox size="lg" label="Large" defaultChecked />
      </Section>

      <Section title="CheckboxGroup · select all">
        <CheckboxGroup
          label="Notify me by"
          description="Pick one or more."
          selectAll
          value={channels}
          onValueChange={setChannels}
          options={[
            { value: "sms", label: "SMS" },
            { value: "email", label: "Email" },
            { value: "whatsapp", label: "WhatsApp", description: "Business account only" },
            { value: "post", label: "Post", disabled: true },
          ]}
        />
      </Section>

      <Section title="CheckboxGroup · horizontal, error">
        <CheckboxGroup label="Days" orientation="horizontal" required error="Choose at least one day.">
          <Checkbox value="mon" label="Mon" />
          <Checkbox value="tue" label="Tue" />
          <Checkbox value="wed" label="Wed" />
        </CheckboxGroup>
      </Section>
    </>
  );
}
```

## Install

```bash
npx @grampro/kit@native add Checkbox
```

## Usage

```tsx
import { Checkbox, CheckboxGroup } from "@/component-lib/checkbox";

<CheckboxGroup label="Notify me by" selectAll defaultValue={["sms"]}>
  <Checkbox value="sms" label="SMS" />
  <Checkbox value="email" label="Email" />
</CheckboxGroup>
```

## Props

### CheckboxProps

| Prop | Type | Description |
|---|---|---|
| `checked` | `CheckedState` | `true`, `false` or `"indeterminate"` (controlled). |
| `defaultChecked` | `CheckedState` | The starting state when you are not controlling `checked`. |
| `onCheckedChange` | `(checked: boolean) => void` | The state after a change, as a plain boolean. Never fires with `"indeterminate"`: pressing a mixed box resolves it. |
| `value` | `string` | Inside a CheckboxGroup, the value this box adds. |
| `label` | `ReactNode` | The text beside the box. Pressing it toggles the box. |
| `description` | `ReactNode` | A hint under the label, read as the box's hint. |
| `error` | `ReactNode` | The validation message. Setting it marks the box invalid and announces it. |
| `size` | `CheckboxSize` | Default `md`, or the size of the CheckboxGroup it sits in. |
| `disabled` | `boolean` |   |
| `required` | `boolean` | Marks the label with an asterisk. Native has no form validation of its own. |
| `style` | `Styleable<ViewStyle>` |   |
| `styles` | `Partial<{ root: Styleable<ViewStyle>; control: Styleable<ViewStyle>; label: Styleable<T…` |   |

Also accepts the props of `Omit<PressableProps, "children" | "style" | "onPress" | "disabled">`.

### CheckboxGroupProps

| Prop | Type | Description |
|---|---|---|
| `value` | `string[]` | Checked values (controlled). |
| `defaultValue` | `string[]` | The values checked to begin with, when you are not controlling `value`. |
| `onValueChange` | `(values: string[]) => void` | The checked values after a change, in the order they were checked. |
| `options` | `readonly CheckboxOption[]` | Render these options, or pass `<Checkbox value="…">` children. |
| `children` | `ReactNode` |   |
| `label` | `ReactNode` | The group's name, shown as its legend. |
| `description` | `ReactNode` |   |
| `error` | `ReactNode` |   |
| `required` | `boolean` |   |
| `disabled` | `boolean` |   |
| `size` | `CheckboxSize` |   |
| `orientation` | `"vertical" \| "horizontal"` | Default `vertical`. |
| `selectAll` | `boolean \| ReactNode` | With `options`, a parent box that checks or clears them all. `true` uses the default label. |
| `style` | `StyleProp<ViewStyle>` |   |
| `styles` | `Partial<{ root: StyleProp<ViewStyle>; legend: StyleProp<TextStyle>; description: StyleP…` |   |
| `localeText` | `Partial<CheckboxLocaleText>` |   |

## Native and web

- The whole row is one target. Indeterminate reports `aria-checked="mixed"`.
- Web version: [Checkbox on the web](https://kit.gramproindia.com/checkbox).