@spark-web/checkbox

title: Checkbox storybookPath: forms-checkbox--default isExperimentalPackage: false

Checkboxes are used to toggle between checked and unchecked states — usually in a form. If only one option from a list is allowed to be enable, consider using a RadioButton instead.

Examples

Controlled

Checkboxes can be both controlled and uncontrolled. To control a checkbox provide the checked state with a value you control, as well as an onChange function to set the new value when the checkbox is toggled.

const [checked, setChecked] = React.useState(false);

return (
  <Stack gap="large">
    <Checkbox
      checked={checked}
      onChange={event => setChecked(event.target.checked)}
    >
      <Text>{checked ? 'Hide' : 'Show'} message</Text>
    </Checkbox>
    {checked && <Text>Toggle the checkbox to hide this message</Text>}
  </Stack>
);

Size

Checkboxes are available in two sizes: small and medium.

<Stack gap="large">
  <Fieldset legend="Checkbox variations (small)" gap="large">
    <Checkbox size="small" checked={false}>
      Unchecked
    </Checkbox>
    <Checkbox size="small" checked>
      Checked
    </Checkbox>
    <Checkbox size="small" disabled>
      Disabled
    </Checkbox>
    <Checkbox size="small" checked disabled>
      Checked + disabled
    </Checkbox>
  </Fieldset>
  <Divider />
  <Fieldset legend="Checkbox variations (medium)" gap="large">
    <Checkbox size="medium" checked={false}>
      Unchecked
    </Checkbox>
    <Checkbox size="medium" checked>
      Checked
    </Checkbox>
    <Checkbox size="medium" disabled>
      Disabled
    </Checkbox>
    <Checkbox size="medium" checked disabled>
      Checked + disabled
    </Checkbox>
  </Fieldset>
</Stack>

Message and tone

The message is used to communicate the status of a field, such as an error message. This will be announced on focus and can be combined with a tone to illustrate intent. The supported tones are: critical, positive and neutral.

<Fieldset legend="Message and tone" gap="large">
  <Checkbox message="Critical message" tone="critical">
    Critical
  </Checkbox>
  <Checkbox message="Positive message" tone="positive">
    Positive
  </Checkbox>
  <Checkbox message="Neutral message" tone="neutral">
    Neutral
  </Checkbox>
</Fieldset>

Props

Checkbox

The Checkbox component also extends InputHTMLAttributes props and are not listed here.

CheckboxPrimitive

The CheckboxPrimitive component also extends InputHTMLAttributes props and are not listed here.