---
name: CheckboxField
menu: 'Components: UI'
route: /components/ui/checkbox-field
---

# CheckboxField

CheckboxField allows users to select one or more options from a set.

import {
  Playground,
  Props,
} from 'docz'
import { CheckboxField } from './CheckboxField'

## Basic Usage

To implement the CheckboxField component, you need to import it first:

```js
import { CheckboxField } from '@react-ui-org/react-ui';
```

And use it:

<Playground>
  {() => {
    const [agree, setAgree] = React.useState(true);
    return (
      <CheckboxField
        changeHandler={() => setAgree(!agree)}
        checked={agree}
        id="my-checkbox"
        label="I agree"
      />
    );
  }}
</Playground>

See [API](#api) for all available options.

## General Guidelines

- Use the CheckboxField when there are lists of options and the user may
  **select any number of choices,** including zero, one, or several. For
  selecting just a single option from the list, use either the
  [Radio](/components/ui/radio) or [SelectField](/components/ui/select-field)
  component.

- Use the CheckboxField for boolean (true/false) input **in forms that require
  to be confirmed** by a button to become active. To toggle things on or off
  with an immediate effect (without confirmation), use rather the
  [Toggle](/components/ui/toggle) component.

- **Use positive wording for the checkbox label,** so that it's clear what will
  happen when the user turns on the checkbox. Avoid negations such as “Don't
  send me any emails” which would mean that the user needs to turn the
  checkbox **on** in order for something **not** to happen.

- Only make the CheckboxField's label invisible when there is **another visual
  clue** to guide users through toggling the input.

- When a short label is not enough, use **help texts to guide users** before
  they enter anything.

- Use **clear, calm error messages** when there's a problem with what they
  entered.

- **Visually present groups of choices as groups,** and clearly separate them
  from other groups on the same page.

📖 [Read more about checkboxes and radios at Nielsen Norman Group.](https://www.nngroup.com/articles/checkboxes-vs-radio-buttons/)

## Help Text

You may provide an additional help text to clarify what will be the impact of
turning the checkbox on or off.

<Playground>
  {() => {
    const [getNewsletter, setGetNewsletter] = React.useState(true);
    return (
      <CheckboxField
        changeHandler={() => setGetNewsletter(!getNewsletter)}
        checked={getNewsletter}
        description="We will not bother you more than once a month, we promise!"
        id="my-checkbox-with-helper-text"
        label="Send me newsletter"
      />
    );
  }}
</Playground>

## Label Options

In some cases, it may be convenient to visually hide the checkbox label. The
label remains accessible to assistive technologies.

<Playground>
  {() => {
    const [checked, setChecked] = React.useState(true);
    return (
      <CheckboxField
        changeHandler={() => setChecked(!checked)}
        checked={checked}
        id="my-checkbox-with-invisible-label"
        isLabelVisible={false}
        label="You cannot see this"
      />
    );
  }}
</Playground>

It's also possible to display the label before the input:

<Playground>
  {() => {
    const [checked, setChecked] = React.useState(true);
    return (
      <CheckboxField
        changeHandler={() => setChecked(!checked)}
        checked={checked}
        id="my-checkbox-with-label-before-input"
        label="The label precedes the input"
        labelPosition="before"
      />
    );
  }}
</Playground>

## States

### Validation States

Validation states visually present the result of validation of the input. You
should always **provide a help text for states other than valid** so users know
what happened and what action they should take or what options they have.

<Playground>
  {() => {
    const [agree, setAgree] = React.useState(true);
    return (
      <>
        <CheckboxField
          changeHandler={() => setAgree(!agree)}
          checked={agree}
          id="my-checkbox-valid"
          label="I agree"
          validationState="valid"
        />
        <CheckboxField
          changeHandler={() => setAgree(!agree)}
          checked={agree}
          description="Please wait 10 minutes until we verify your data."
          id="my-checkbox-warning"
          label="I agree"
          validationState="warning"
        />
        <CheckboxField
          changeHandler={() => setAgree(!agree)}
          checked={agree}
          error="You must agree to be able to proceed."
          id="my-checkbox-invalid"
          label="I agree"
          required
          validationState="invalid"
        />
      </>
    );
  }}
</Playground>

### Disabled State

Disabled state makes the input unavailable.

<Playground>
  <CheckboxField
    label="Disabled checkbox"
    id="my-checkbox-disabled"
    disabled
  />
  <CheckboxField
    label="Disabled checkbox, checked"
    id="my-checkbox-checked-disabled"
    disabled
    checked
  />
</Playground>

## API

In addition to the options below, you can add any custom attributes that do not
interfere with the API, and they will be passed to the `input` HTML element.
This is useful mainly to improve component's accessibility.

<Props of={CheckboxField} />

---

Next: [Modal →](/components/ui/modal)
