Checkbox

Use the checkbox component to select one or more options of a limited number of choices.

Experimental
Not reviewed for accessibility

On this page

Examples

Please use FormControl 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.

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

<form>
  <FormControl>
    <FormControl.Label>Default checkbox</FormControl.Label>
    <Checkbox />
  </FormControl>
  <FormControl>
    <FormControl.Label>Always checked</FormControl.Label>
    <Checkbox checked />
  </FormControl>
  <FormControl>
    <FormControl.Label>Always unchecked</FormControl.Label>
    <Checkbox checked={false} />
  </FormControl>
  <FormControl>
    <FormControl.Label>Inactive</FormControl.Label>
    <Checkbox checked disabled />
  </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.

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

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

Optional border

Apply an optional border using FormControl and hasBorder.

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

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

Custom label usage

<FormControl required>
  <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>
  <Checkbox />
</FormControl>

<FormControl required>
  <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>
  <Checkbox />
</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	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 to the checkbox
`ref`	`React.RefObject`	Forward a Ref to the underlying DOM node
`validationStatus`	`'error'` `'success'`	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 accepted by the <input> element.

FormControl