v1.0.11

Checkbox

Stable

This component is considered stable. Reach out to the Spark team to find out more about what this means.

Open in Storybook Edit this page

Installation

Install yarn add @spark-web/checkbox

npm @spark-web/checkbox

Source GitHub.com

Bundle unpkg.com

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.

Show message

Open in Playroom

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>
);

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.

Open in Playroom

<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>

<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.

Message and tone

Critical

Critical message

Positive

Positive message

Neutral

Neutral message

Open in Playroom

<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>

<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

Prop	Type	Description
checked?	boolean	When true, the checkbox will be checked.
children?	ReactNode: string \| number \| false \| true \| {} \| ReactElement<any, string \| JSXElementConstructor<any>> \| Iterable<ReactNode> \| ReactPortal	The checkbox label content.
data?	DataAttributeMap	Sets data attributes on the component.
disabled?	boolean	When true, the checkbox will be disabled. Default: `false`
message?	string	Provide a message, informing the user about changes in state.
size?	CheckboxSize: "small" \| "medium"	The size of the checkbox. Default: `"small"`
tone?	"critical" \| "positive" \| "neutral"	Provide a tone to influence elements of the field, and its input. Default: `"neutral"`
value?	string	The value of the checkbox.

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

CheckboxPrimitive

Prop	Type	Description
checked?	boolean	When true, the checkbox will be checked.
data?	DataAttributeMap	Sets data attributes on the component.
disabled?	boolean	When true, the checkbox will be disabled.
size?	CheckboxSize: "small" \| "medium"	The size of the checkbox. Default: `"small"`
value?	string	The value of the checkbox.

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