---
title: Checkbox | UI
description: A Checkbox component is used to provide a way for users to select one or more options from a set of predefined choices.
pageTitle: Checkbox
pageDescription: A Checkbox component is used to provide a way for users to select one or more options from a set of predefined choices.
showHeader: true
---

import { Meta } from '@storybook/addon-docs';

<Meta title="components/Forms/Checkbox" />

import { Checkbox, CheckIcon } from './Checkbox';
import { Center, VStack, Text as CheckboxText } from './Checkbox';
import { transformedCode } from '../../../utils';
import {
  AppProvider,
  CodePreview,
  Table,
  InlineCode,
} from '@gluestack/design-system';

import { styled } from '@dank-style/react';

import Wrapper from '../../Wrapper';

# Installation

This command copies the `Checkbox` component to your project.

```jsx
npx install @gluestack-ui add checkbox
```

## Import

```jsx
// import the component from your component folder
import { Checkbox } from 'components';
```

<br />

# Basic

<AppProvider>
  <CodePreview
    showComponentRenderer={true}
    showArgsController={false}
    metaData={{
      code: `
<Checkbox>
  <Checkbox.Indicator>
    <Checkbox.Icon>
        <CheckIcon />
    </Checkbox.Icon>
  </Checkbox.Indicator>
   <Checkbox.Label>Label</Checkbox.Label>
</Checkbox>
`,
      transformCode: (code) => {
        return transformedCode(code);
      },
      scope: {
        Wrapper,
        CheckIcon,
        Checkbox,
      },
      argsType: {},
    }}
  />
</AppProvider>
<br />

## Anatomy

The checkbox component consists of the following parts:

```jsx
export default () => (
  <Checkbox.Group>
    <Checkbox>
      <Checkbox.Indicator>
        <Checkbox.Icon>
          <CheckIcon />
        </Checkbox.Icon>
      </Checkbox.Indicator>
    </Checkbox>
  </Checkbox.Group>
);
```

## API Reference

### Checkbox

Contains all Checkbox related layout style props and actions.
It inherits all the properties of React Native's [View](https://reactnative.dev/docs/view#props) component.

<AppProvider>
  <Table>
    <Table.THead>
      <Table.TR>
        <Table.TH>
          <Table.TText>Prop</Table.TText>
        </Table.TH>
        <Table.TH>
          <Table.TText>Type</Table.TText>
        </Table.TH>
        <Table.TH>
          <Table.TText>Default</Table.TText>
        </Table.TH>
        <Table.TH>
          <Table.TText>Description</Table.TText>
        </Table.TH>
      </Table.TR>
    </Table.THead>
    <Table.TBody>
      <Table.TR>
        <Table.TD>
          <Table.TText>
            <InlineCode>value</InlineCode>
          </Table.TText>
        </Table.TD>
        <Table.TD>
          <Table.TText>string</Table.TText>
        </Table.TD>
        <Table.TD>
          <Table.TText>-</Table.TText>
        </Table.TD>
        <Table.TD>
          <Table.TText>{`The value to be used in the checkbox input. This is the value that will be returned on form submission.`}</Table.TText>
        </Table.TD>
      </Table.TR>
      <Table.TR>
        <Table.TD>
          <Table.TText>
            <InlineCode>onChange</InlineCode>
          </Table.TText>
        </Table.TD>
        <Table.TD>
          <Table.TText>function</Table.TText>
        </Table.TD>
        <Table.TD>
          <Table.TText>-</Table.TText>
        </Table.TD>
        <Table.TD>
          <Table.TText>{`Function called when the state of the checkbox changes.`}</Table.TText>
        </Table.TD>
      </Table.TR>
      <Table.TR>
        <Table.TD>
          <Table.TText>
            <InlineCode>defaultIsChecked</InlineCode>
          </Table.TText>
        </Table.TD>
        <Table.TD>
          <Table.TText>bool</Table.TText>
        </Table.TD>
        <Table.TD>
          <Table.TText>false</Table.TText>
        </Table.TD>
        <Table.TD>
          <Table.TText>{`If true, the checkbox will be initially checked.`}</Table.TText>
        </Table.TD>
      </Table.TR>
      <Table.TR>
        <Table.TD>
          <Table.TText>
            <InlineCode>isChecked</InlineCode>
          </Table.TText>
        </Table.TD>
        <Table.TD>
          <Table.TText>bool</Table.TText>
        </Table.TD>
        <Table.TD>
          <Table.TText>false</Table.TText>
        </Table.TD>
        <Table.TD>
          <Table.TText>{`When true, the checkbox will be checked. You'll need to pass onChange to update it's value (since it's now controlled).`}</Table.TText>
        </Table.TD>
      </Table.TR>
      <Table.TR>
        <Table.TD>
          <Table.TText>
            <InlineCode>isDisabled</InlineCode>
          </Table.TText>
        </Table.TD>
        <Table.TD>
          <Table.TText>bool</Table.TText>
        </Table.TD>
        <Table.TD>
          <Table.TText>false</Table.TText>
        </Table.TD>
        <Table.TD>
          <Table.TText>{`To manually set disable to the checkbox.`}</Table.TText>
        </Table.TD>
      </Table.TR>
      <Table.TR>
        <Table.TD>
          <Table.TText>
            <InlineCode>isInvalid</InlineCode>
          </Table.TText>
        </Table.TD>
        <Table.TD>
          <Table.TText>bool</Table.TText>
        </Table.TD>
        <Table.TD>
          <Table.TText>false</Table.TText>
        </Table.TD>
        <Table.TD>
          <Table.TText>{`To manually set invalid to the checkbox.`}</Table.TText>
        </Table.TD>
      </Table.TR>
      <Table.TR>
        <Table.TD>
          <Table.TText>
            <InlineCode>isReadOnly</InlineCode>
          </Table.TText>
        </Table.TD>
        <Table.TD>
          <Table.TText>bool</Table.TText>
        </Table.TD>
        <Table.TD>
          <Table.TText>false</Table.TText>
        </Table.TD>
        <Table.TD>
          <Table.TText>{`To manually set read-only to the checkbox.`}</Table.TText>
        </Table.TD>
      </Table.TR>
      <Table.TR>
        <Table.TD>
          <Table.TText>
            <InlineCode>isHovered</InlineCode>
          </Table.TText>
        </Table.TD>
        <Table.TD>
          <Table.TText>bool</Table.TText>
        </Table.TD>
        <Table.TD>
          <Table.TText>false</Table.TText>
        </Table.TD>
        <Table.TD>
          <Table.TText>{`To manually set hover to the checkbox.`}</Table.TText>
        </Table.TD>
      </Table.TR>
      <Table.TR>
        <Table.TD>
          <Table.TText>
            <InlineCode>isFocusVisible</InlineCode>
          </Table.TText>
        </Table.TD>
        <Table.TD>
          <Table.TText>bool</Table.TText>
        </Table.TD>
        <Table.TD>
          <Table.TText>false</Table.TText>
        </Table.TD>
        <Table.TD>
          <Table.TText>
            {`To manually set focus visible state to the checkbox.`}
          </Table.TText>
        </Table.TD>
      </Table.TR>
      <Table.TR>
        <Table.TD>
          <Table.TText>
            <InlineCode>isIndeterminate</InlineCode>
          </Table.TText>
        </Table.TD>
        <Table.TD>
          <Table.TText>bool</Table.TText>
        </Table.TD>
        <Table.TD>
          <Table.TText>false</Table.TText>
        </Table.TD>
        <Table.TD>
          <Table.TText>
            {`To manually set indeterminate to the checkbox.`}
          </Table.TText>
        </Table.TD>
      </Table.TR>
    </Table.TBody>
  </Table>
</AppProvider>

### Checkbox.Indicator

Contains all Indicator related layout style props and actions.
It inherits all the properties of React Native's [View](https://reactnative.dev/docs/view#props) component.

### Checkbox.Indicator

Contains all Indicator related layout style props and actions.
It inherits all the properties of React Native's [View](https://reactnative.dev/docs/view#props) component.

## Checkbox.Icon

Contains all Icon related layout style props and actions.
It inherits all the properties of React Native's [View](https://reactnative.dev/docs/view#props) component.

## Checkbox.Label

Contains all Label related layout style props and actions.
It inherits all the properties of React Native's [Text](https://reactnative.dev/docs/text#props) component.

## Checkbox.Group

Contains all Group related layout style props and actions.
It inherits all the properties of React Native's [View](https://reactnative.dev/docs/view#props) component.

<AppProvider>
  <Table>
    <Table.THead>
      <Table.TR>
        <Table.TH>
          <Table.TText>Prop</Table.TText>
        </Table.TH>
        <Table.TH>
          <Table.TText>Type</Table.TText>
        </Table.TH>
        <Table.TH>
          <Table.TText>Default</Table.TText>
        </Table.TH>
        <Table.TH>
          <Table.TText>Description</Table.TText>
        </Table.TH>
      </Table.TR>
    </Table.THead>
    <Table.TBody>
      <Table.TR>
        <Table.TD>
          <Table.TText>
            <InlineCode>value</InlineCode>
          </Table.TText>
        </Table.TD>
        <Table.TD>
          <Table.TText>string[]</Table.TText>
        </Table.TD>
        <Table.TD>
          <Table.TText>-</Table.TText>
        </Table.TD>
        <Table.TD>
          <Table.TText>{`The value of the checkbox group.`}</Table.TText>
        </Table.TD>
      </Table.TR>
      <Table.TR>
        <Table.TD>
          <Table.TText>
            <InlineCode>onChange</InlineCode>
          </Table.TText>
        </Table.TD>
        <Table.TD>
          <Table.TText>function</Table.TText>
        </Table.TD>
        <Table.TD>
          <Table.TText>-</Table.TText>
        </Table.TD>
        <Table.TD>
          <Table.TText>{`The callback fired when any children Checkbox is checked or unchecked.`}</Table.TText>
        </Table.TD>
      </Table.TR>
    </Table.TBody>
  </Table>
</AppProvider>

## Features

- Keyboard support for actions.
- Support for hover, focus and active states.

## Accessibility

### Keyboard

- Tab: Moves focus to the next focusable element.
- `Shift + Tab`: Moves focus to the previous focusable element.
- Space: To check or uncheck focused checkbox.

### Screen Reader

- VoiceOver: When the checkbox is focused, the screen reader will announce it's a checkbox and it's current state (check or uncheck) and it's label.

## Dependencies

- `@react-native-aria/checkbox`
- `@react-native-aria/focus`
- `@gluestack-ui/form-control`
- `@gluestack-ui/react-native-aria`
- `@gluestack-ui/utils`
- `react-native-svg`

<br />
<br />

## Examples

### Checkbox Sizes

<AppProvider>
  <CodePreview
    showComponentRenderer={true}
    showArgsController={false}
    metaData={{
      code: `
<Center>
  <Checkbox size="sm">
    <Checkbox.Indicator>
      <Checkbox.Icon>
        <CheckIcon />
      </Checkbox.Icon>
    </Checkbox.Indicator>
    <Checkbox.Label>Label</Checkbox.Label>
  </Checkbox>
  <Checkbox size="md">
    <Checkbox.Indicator>
      <Checkbox.Icon>
        <CheckIcon />
      </Checkbox.Icon>
    </Checkbox.Indicator>
    <Checkbox.Label>Label</Checkbox.Label>
  </Checkbox>
  <Checkbox size="lg">
    <Checkbox.Indicator>
      <Checkbox.Icon>
        <CheckIcon />
      </Checkbox.Icon>
    </Checkbox.Indicator>
    <Checkbox.Label>Label</Checkbox.Label>
  </Checkbox>
</Center>
`,
      transformCode: (code) => {
        return transformedCode(code);
      },
      scope: { Checkbox, Wrapper, Center, CheckIcon },
      argsType: {},
    }}
  />
</AppProvider>

### Checkbox states

<AppProvider>
  <CodePreview
    showComponentRenderer={true}
    showArgsController={false}
    metaData={{
      code: `
<VStack alignItems="$start">
  <Checkbox isInvalid={true}>
    <Checkbox.Indicator>
      <Checkbox.Icon>
        <CheckIcon />
      </Checkbox.Icon>
    </Checkbox.Indicator>
    <Checkbox.Label>isInvalid</Checkbox.Label>
  </Checkbox>
  <Checkbox isReadOnly={true}>
    <Checkbox.Indicator>
      <Checkbox.Icon>
        <CheckIcon />
      </Checkbox.Icon>
    </Checkbox.Indicator>
    <Checkbox.Label>isReadOnly</Checkbox.Label>
  </Checkbox>
  <Checkbox isDisabled={true}>
    <Checkbox.Indicator>
      <Checkbox.Icon>
        <CheckIcon />
      </Checkbox.Icon>
    </Checkbox.Indicator>
    <Checkbox.Label>isDisabled</Checkbox.Label>
  </Checkbox>
  <Checkbox isChecked={true}>
    <Checkbox.Indicator>
      <Checkbox.Icon>
        <CheckIcon />
      </Checkbox.Icon>
    </Checkbox.Indicator>
    <Checkbox.Label>isChecked</Checkbox.Label>
  </Checkbox>
</VStack>
`,
      transformCode: (code) => {
        return transformedCode(code);
      },
      scope: { Checkbox, Wrapper, VStack, CheckIcon },
      argsType: {},
    }}
  />
</AppProvider>

### Checkbox group

<AppProvider>
  <CodePreview
    showComponentRenderer={true}
    showArgsController={false}
    metaData={{
      code: `
function CheckboxExample(){
  const [values, setValues] = React.useState([]);
  return (
    <Wrapper>
      <Center>
        <Checkbox.Group
          value={values}
          onChange={setValues}
        >
          <Checkbox
           isDisabled={true}
            value="Label 1"
            aria-label="Label 1"
            accessibilityLabel="Checkbox"
            onChange={(isSelected) =>
            console.log("hello")
            }
          >
            <Checkbox.Indicator>
              <Checkbox.Icon>
                <CheckIcon />
              </Checkbox.Icon>
            </Checkbox.Indicator>
            <Checkbox.Label>Label 1</Checkbox.Label>
          </Checkbox>
          <Checkbox
            aria-label="Label 2"
            value="Label 2"
            accessibilityLabel="Checkbox"
            onChange={(isSelected) =>console.log("hello")
            }
          >
            <Checkbox.Indicator>
              <Checkbox.Icon>
                <CheckIcon />
              </Checkbox.Icon>
            </Checkbox.Indicator>
            <Checkbox.Label>Label 2</Checkbox.Label>
          </Checkbox>
        </Checkbox.Group>
      </Center>
    </Wrapper>
  );
};
`,
      scope: { Checkbox, Wrapper, Center, CheckIcon },
      argsType: {},
    }}
  />
</AppProvider>

<br />

# Advanced

## Customizing the Checkbox

We have a function called `createCheckbox` which can be used to create a custom checkbox component. This function takes in a configuration object which contains the styled components that you want to use for the checkbox. You can refer [dank.style](https://dank.style/) for more information on how to use styled components.

### Usage

```jsx
// import the styles
import {
  Root,
  Indicator,
  Icon,
  Label,
  Group,
} from '../components/core/checkbox/styled-components';

// import the createCheckbox function
import { createCheckbox } from '@gluestack-ui/checkbox';

// Understanding the API
const Checkbox = createCheckbox({
  Root,
  Indicator,
  Icon,
  Label,
  Group,
});

// Using the checkbox component
export default () => (
  <Checkbox.Group>
    <Checkbox>
      <Checkbox.Indicator>
        <Checkbox.Icon>
          <CheckIcon />
        </Checkbox.Icon>
      </Checkbox.Indicator>
    </Checkbox>
  </Checkbox.Group>
);
```

Default styling of all these components can be found in the `components/core/checkbox` file. For reference, you can view the [source code](https://github.com/gluestack/gluestack-ui/blob/development/example/storybook/src/components/Checkbox/index.tsx) of the styled `Checkbox` components.