Forma 36 - Checkbox

Import

import { Checkbox } from '@contentful/f36-components';
// or
import { Checkbox } from '@contentful/f36-forms';

Examples

Using as a controlled input

Controlled components in React are those in which form data is handled by the component’s state.

For using the Checkbox as a controlled input, you need to:

Pass the isChecked property, with this property it will already be a controlled component;
Pass a onChange handler, so you can use it to update the value of isChecked;

Setting the isChecked will already define it as a controlled input.


function CheckboxControlledExample() {
  const [checkboxState, setCheckboxState] = useState(false);

  return (
    <Checkbox
      name="newsletter-subscribe-controlled"
      id="newsletter-subscribe-controlled"
      isChecked={checkboxState}
      onChange={() => setCheckboxState(!checkboxState)}
    >
      Subscribe to newsletter
    </Checkbox>
  );
}function CheckboxControlledExample() {
  const [checkboxState, setCheckboxState] = useState(false);

  return (
    <Checkbox
      name="newsletter-subscribe-controlled"
      id="newsletter-subscribe-controlled"
      isChecked={checkboxState}
      onChange={() => setCheckboxState(!checkboxState)}
    >
      Subscribe to newsletter
    </Checkbox>
  );
}
Open in Playground

Using as an uncontrolled input

Uncontrolled components are those for which the form data is handled by the DOM itself. “Uncontrolled” refers to the fact that these components are not controlled by React state.

You can use the Checkbox as an uncontrolled input, for that you can:

Set the defaultChecked property, it will ensure that the checked state can be altered normally.
Don't set the isChecked as it will make the input controlled.


function CheckboxUncontrolledExample() {
  return (
    <Checkbox
      name="newsletter-subscribe-uncontrolled"
      id="newsletter-subscribe-uncontrolled"
      defaultChecked
    >
      Subscribe to newsletter
    </Checkbox>
  );
}function CheckboxUncontrolledExample() {
  return (
    <Checkbox
      name="newsletter-subscribe-uncontrolled"
      id="newsletter-subscribe-uncontrolled"
      defaultChecked
    >
      Subscribe to newsletter
    </Checkbox>
  );
}
Open in Playground

Using with Group

We also provide the Checkbox.Group component that helps when using multiple checkboxes. You can pass some common properties on the Checkbox.Group level and they will be passed to the checkboxes inside the group.

spacing: This will set how much space should be between the inputs;
name: By setting this property on the Checkbox.Group level, you will set it automatically for all the checkboxes in the group;
defaultValue: This accepts an array that set the defaultChecked property for checkboxes which the value exists in the array;
value: Same as defaultValue but this one sets the isChecked property, making the checkbox group controlled;
onChange: Handler that will be executed when any checkbox inside the group receives the event of change.

Checkbox.Group is a recommended way of using Checkbox when using it within forms.


function CheckboxGroupExample() {
  return (
    <FormControl as="fieldset">
      <FormControl.Label as="legend" marginBottom="none">
        Checkbox group options
      </FormControl.Label>
      <Paragraph>Subtitle with more information if needed</Paragraph>
      <Checkbox.Group name="checkbox-options" defaultValue={['option 1']}>
        <Checkbox value="option 1" id="option-1" helpText="Some help text">
          Option 1
        </Checkbox>
        <Checkbox value="option 2" id="option-2" helpText="Another help text">
          Option 2
        </Checkbox>
      </Checkbox.Group>
    </FormControl>
  );
}function CheckboxGroupExample() {
  return (
    <FormControl as="fieldset">
      <FormControl.Label as="legend" marginBottom="none">
        Checkbox group options
      </FormControl.Label>
      <Paragraph>Subtitle with more information if needed</Paragraph>
      <Checkbox.Group name="checkbox-options" defaultValue={['option 1']}>
        <Checkbox value="option 1" id="option-1" helpText="Some help text">
          Option 1
        </Checkbox>
        <Checkbox value="option 2" id="option-2" helpText="Another help text">
          Option 2
        </Checkbox>
      </Checkbox.Group>
    </FormControl>
  );
}
Open in Playground

Checked or indeterminate

The Checkbox can be rendered as indeterminate or checked, with the isIndeterminate, and isChecked or defaultChecked properties. Note that providing the isChecked makes it a controlled input, requiring an onChange handler.


function CheckboxCheckedOrIndeterminateExample() {
  return (
    <Flex flexDirection="column">
      <Checkbox id="checkbox1" name="checked-option-1" defaultChecked>
        Option 1 (uncontrolled checked)
      </Checkbox>
      <Checkbox
        id="checkbox1"
        name="controlled-option-2"
        isChecked
        onChange={() => {}}
      >
        Option 2 (controlled checked)
      </Checkbox>
      <Checkbox id="checkbox2" name="indeterminate-option-3" isIndeterminate>
        Option 3 (indeterminate)
      </Checkbox>
    </Flex>
  );
}function CheckboxCheckedOrIndeterminateExample() {
  return (
    <Flex flexDirection="column">
      <Checkbox id="checkbox1" name="checked-option-1" defaultChecked>
        Option 1 (uncontrolled checked)
      </Checkbox>
      <Checkbox
        id="checkbox1"
        name="controlled-option-2"
        isChecked
        onChange={() => {}}
      >
        Option 2 (controlled checked)
      </Checkbox>
      <Checkbox id="checkbox2" name="indeterminate-option-3" isIndeterminate>
        Option 3 (indeterminate)
      </Checkbox>
    </Flex>
  );
}
Open in Playground

Disabled

The Checkbox can be rendered as disabled with the isDisabled property.


function CheckboxDisabledExample() {
  return (
    <Flex flexDirection="column">
      <Checkbox id="checkbox3" name="disabled-option-1" isDisabled>
        Option 1
      </Checkbox>
      <Checkbox id="checkbox4" name="disabled-option-2" isChecked isDisabled>
        Option 2 (checked)
      </Checkbox>
      <Checkbox
        id="checkbox5"
        name="disabled-option-3"
        isIndeterminate
        isDisabled
      >
        Option 3 (indeterminate)
      </Checkbox>
    </Flex>
  );
}function CheckboxDisabledExample() {
  return (
    <Flex flexDirection="column">
      <Checkbox id="checkbox3" name="disabled-option-1" isDisabled>
        Option 1
      </Checkbox>
      <Checkbox id="checkbox4" name="disabled-option-2" isChecked isDisabled>
        Option 2 (checked)
      </Checkbox>
      <Checkbox
        id="checkbox5"
        name="disabled-option-3"
        isIndeterminate
        isDisabled
      >
        Option 3 (indeterminate)
      </Checkbox>
    </Flex>
  );
}
Open in Playground

Content guidelines

Use direct, succinct copy that helps the user to successfully complete the form
Do not use punctuation for labels
Use sentence style caps (in which only the first word of a sentence or term is capitalized)

Accessibility

Each checkbox is independently controlled, where you can enable multiple identifiable options.
To ensure the Checkbox meets accessibility keyboard standards, set the name and id properties.

Checkbox Group

Set the name prop to give each indivual value the same name
The Checkbox.Group should be wrapped in a <FormControl as="fieldset">
In order to easier identify the indivual Checkboxes as a group and set a label via <FormControl.Label as="legend">.
For more information about validation and controlling form fields, please refer to FormControl.

Keyboard Usage

To switch between options, use the “tab + space” command on the keyboard.
To check and uncheck the checkboxes, hit “space” on the keyboard.

Props (API reference)

Open in Storybook

Props Checkbox

Name	Type	Default
aria-label	string Value to be set as aria-label if not passing a children
className	string CSS class to be appended to the root element
css	string number false true ComponentSelector Keyframes SerializedStyles ArrayInterpolation<undefined> ObjectInterpolation<undefined> (theme: any) => Interpolation<undefined>
defaultChecked	false true Defines initial checked state for an uncontrolled component	false
density	"low" "high"
helpText	string Optional text to be added as help text bellow the label
id	string Sets the id of the input
inputProps	Partial<Pick<DetailedHTMLProps<InputHTMLAttributes<HTMLInputElement>, HTMLInputElement>, "key" \| keyof InputHTMLAttributes<...>>> & { ...; } Additional props that are passed to the input element
isChecked	false true Defines if the element is checked, onChange will be required	undefined
isDisabled	false true Applies disabled styles	false
isIndeterminate	false true Defines if the state is indeterminate	false
isInvalid	false true Applies invalid styles	false
isRequired	false true Validate the input	false
name	string Set the name of the input
onBlur	FocusEventHandler<HTMLInputElement \| HTMLTextAreaElement> Allows to listen to an event when an element loses focus
onChange	ChangeEventHandler<HTMLInputElement> Allows to listen to an input’s change in value
onFocus	FocusEventHandler<HTMLInputElement \| HTMLTextAreaElement> Allows to listen to an event when an element get focused
onKeyDown	KeyboardEventHandler<HTMLInputElement \| HTMLTextAreaElement> Allows to listen to an event when a key is pressed
resize	"none" "both" "horizontal" "vertical" Sets whether an element is resizable, and if so, in which directions	vertical
testId	string A [data-test-id] attribute used for testing purposes
value	string Set the value of the input
willBlurOnEsc	false true Boolean property that allows to blur on escape	true

Props Group

Name	Type	Default
children required	ReactNode Elements that should be in the group
className	string CSS class to be appended to the root element
defaultValue	string[] Array of values of the checkboxes that should be checked for uncontrolled inputs
name	string Name that will be assigned to all checkboxes inside the group, unless a different name is passed to the checkbox
onBlur	FocusEventHandler<HTMLInputElement> Handler that will be triggered when any checkbox inside the group loses focus
onChange	ChangeEventHandler<HTMLInputElement> Handler that will be triggered when any checkbox inside the group has their checked state changed
testId	string A [data-test-id] attribute used for testing purposes
value	string[] Array of values of the checkboxes that should be checked for controlled inputs

Density support

This component supports multiple densities thanks to the useDensity hook and automatically adjusts its styling for each density (when wrapped with the DensityProvider).