@primer/react-brand/docs/forms/Checkbox/react.md

Primer Brand is a GitHub's design system for creating React-based marketing websites and digital experiences.

---
title: Checkbox
source: https://github.com/primer/brand/blob/main/packages/react/src/forms/Checkbox/Checkbox.tsx
keywords: ['form', 'control', 'selection', 'choices']
figma: 'https://www.figma.com/file/BJ95AjraesmRCWsKA013GS/Primer-Brand?node-id=1377%3A30754'
storybook: '/brand/storybook/?path=/story/components-forms-checkbox--playground'
description: Use the checkbox component to select one or more options of a limited number of choices.
---

## Examples

> **Please use [FormControl](../FormControl/index.md) to display accessible checkboxes in the UI**. This `Checkbox` component is intended only as an ingredient for other custom components, or as a drop-in replacement for native HTML checkboxes outside of form use-cases.
>
> If you intend to use this component as part of another component, it should always be accompanied by a corresponding `<label>` to improve support for assistive technologies.

The `Checkbox` component can be used in controlled and uncontrolled modes.

```jsx
<form>
  <FormControl>
    <Checkbox />
    <FormControl.Label>Default checkbox</FormControl.Label>
  </FormControl>
  <FormControl>
    <Checkbox checked />
    <FormControl.Label>Always checked</FormControl.Label>
  </FormControl>
  <FormControl>
    <Checkbox checked={false} />
    <FormControl.Label>Always unchecked</FormControl.Label>
  </FormControl>
  <FormControl>
    <Checkbox checked disabled />
    <FormControl.Label>Inactive</FormControl.Label>
  </FormControl>
</form>
```

## Indeterminate

An `indeterminate` checkbox state should be used if the input value is neither `true` nor `false`. This can be useful in situations where you are required to display an incomplete state, or one that is dependent on other input selections to determine a value.

```jsx
<form>
  <FormControl>
    <Checkbox onChange={() => {}} indeterminate={true} />
    <FormControl.Label>Indeterminate checkbox</FormControl.Label>
  </FormControl>
</form>
```

## Optional border

Apply an optional border using `FormControl` and `hasBorder`.

```jsx
<FormControl hasBorder required>
  <Checkbox />
  <FormControl.Label>Contact me about GitHub Enterprise Server</FormControl.Label>
</FormControl>
```

## Custom label usage

When using a custom label alongside a checkbox, the `Checkbox` component should always appear after the `FormControl.Label` component in the DOM. This ensures that the checkbox is correctly associated with the label for assistive technologies.

```jsx
<FormControl required>
  <Checkbox />
  <FormControl.Label>
    <Text size="200" variant="muted">
      I hereby accept the{' '}
      <InlineLink size="200" href="https://github.com/customer-terms" target="_blank">
        GitHub Customer Agreement
      </InlineLink>{' '}
      on behalf of my organization and confirm that I have the authority to do so. For more information about
      GitHub&apos;s privacy practices, see the{' '}
      <InlineLink
        size="200"
        href="https://docs.github.com/en/site-policy/privacy-policies/github-privacy-statement"
        target="_blank"
      >
        GitHub Privacy Statement.
      </InlineLink>
    </Text>
  </FormControl.Label>
</FormControl>
```

## Component props

`Checkbox` provides a React alternative to the native HTML `<input type="checkbox">`.

The component API supports all standard HTML attribute props, while providing some additional behavior as described below.

| Name               | Type              | Default | Description                                                                                                                                   |
| :----------------- | :---------------- | :-----: | :-------------------------------------------------------------------------------------------------------------------------------------------- |
| `checked`          | `boolean`         |         | Modifies true/false value of the native checkbox                                                                                              |
| `className`        | `string`          |         | Sets a custom class                                                                                                                           |
| `defaultChecked`   | `boolean`         |         | Checks the input by default in uncontrolled mode                                                                                              |
| `disabled`         | `boolean`         |         | Modifies the native disabled state of the native checkbox                                                                                     |
| `id`               | `string`          |         | Sets a custom id                                                                                                                              |
| `indeterminate`    | `boolean`         |         | Applies an [indeterminate state](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/checkbox#attr-indeterminate) to the checkbox |
| `ref`              | `React.RefObject` |         | Forward a Ref to the underlying DOM node                                                                                                      |
| `validationStatus` |                   |         | Ussed to inform ARIA attributes. Individual checkboxes do not have validation styles.                                                         |

Additional props can be passed to the `<input>` element. [See MDN for a list of props](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input) accepted by the `<input>` element.

## Related components

- FormControl