Checkbox

Interface of Checkbox
🏗 Coming Soon

The <Checkbox /> component renders a single checkbox element on the page, with no accompanying label. It is generally used to construct higher-order components like the <FieldCheckbox />. If you are building a form, you probably want to use <FieldCheckbox /> instead as it provides label support.

Checked Property

The <Checkbox /> component can be rendered in three different states: checked, unchecked, and "mixed". In addition to the standard boolean, rendering a "mixed" value can be used to indicate that only a fraction of related sub-options have been selected.

Note: The "mixed" value is only available to the checked property and not available to defaultChecked property.

Check Mark Mixed

onChange Property

Checkbox accepts an onChange callback, which can be used for toggling checkbox state.

Advanced Use: Controlling parent/child mixed states

Using a mixed state checkbox can be used to establish a parent and child relationship between multiple options. This is an advanced use and will likely require bespoke state management. In an attempt to facilitate a standard UX, we've create a hook and state pattern.

This may not be sufficient for your own use case, but it may provide a good starting point and reference for how it should work.

Name and ID

A name and ID can be specified in the <Checkbox /> component. Names are important if the checkbox is used in the context of a form, in which case a name is required for the value of the checkbox to be captured.

Disabled Property

Use the disable property to gray out the checkbox, making it unclickable.

Check Mark Mixed

ReadOnly property

Checkbox will ignore user-actions on a Checkbox with the readOnly property enabled, similar to disabled but without greying out the option.

NOTE: In HTML specifying readonly on only prevents changes to value attribute of the checkbox and therefore allowing the user to still check and uncheck the checkbox.

In most cases we emulate the HTML specification where it has an existing decision or feature. However, the specification's behavior around checkboxes with a readonly attribute is rather unintuitive.

Check Mark Mixed

Accessibility

Best Practices

  • Individual checkboxes must have an onscreen <Label>
  • Groups of checkboxes must have group label, using the <Fieldset> and <legend> tags.
  • See related ARIA attributes

Markup Expectations

  • Always include an unique id on the checkbox element so it can be referenced by a label <Checkbox id="agree">

Labeling Expectations

  • Use clear and descriptive labels that avoid ambiguity.
  • Always include a <Label> with a for property that matches the checkbox id.
  • Groups of checkboxes must be wrapped in a <fieldset> and have <legend> that describes the group. We recommend utilizing CheckboxGroup for these use cases.

Focus Expectations

  • checkboxes with :focus should have an outline and/or a visible change to show it has focus.
  • If the checkbox with :focus has an error, the error should be read by a screen reader

Keyboard Expectations

  • If checkbox has focus the SPACE key should toggle the state.
  • If checkbox has focus the Enter key should submit the form.
  • If checkbox has focus, TAB and SHIFT+TAB should move focus to next focusable element.

aria-describedby

Use this to provide a detailed descriptions of a field that contains errors.

This would announce "Approve, unchecked checkbox. Confirm you approve these changes."