Checkbox

Checkboxes allow a user to select zero, one, or multiple values from a predefined list of 7 or less options.

GitHubStorybook
yarn add @workday/canvas-kit-react
Sources
GitHubStorybook
Install
yarn add @workday/canvas-kit-react

Anatomy

Image of a Checkbox Group in its default state.

  1. Form Field Label: The Form Field Label describes all of the checkboxes in the checkbox group and functions as a header.
  2. Checkbox: Checkboxes are aligned close to its label or by itself in some cases.
  3. Checkbox Label: Checkbox Labels give information about what to select or unselect.

Usage Guidance

  • The Form Field Label can be positioned in two places; above or left of the checkbox group for LTR languages. Form Field Labels are aligned to the right of the checkbox group for RTL languages.
  • Checkbox Labels are positioned to the right of Checkboxes for LTR languages or to the left of Checkboxes for RTL languages.
  • Checkboxes allow users to select one or many options. Selected options are shown as a white check with blue fill. Clicking it again will deselect the choice.
  • Each Checkbox is tied to a distinct value. Label for each selection should describe the choice and be kept as concise as possible. See these guidelines for more information on writing Checkbox labels.

When to Use

  • Use Checkboxes when the user is allowed to select 0, 1, or multiple values from a predefined list of 7 or less options.

When to Use Something Else

  • Consider using a Switch if the only options are yes or no.
  • For a list between 2 to 7 predefined options, consider using Radio Buttons or a Select to select one option.
  • Use a Prompt when the number of list items is large or unknown. Prompts have search capabilities and folders which provide users with the means to browse options. Prompts can be configured to support single or multi-select.

Examples

Basic Example

Checkbox may be used on its own without Form Field since it includes a <label> with a for attribute referencing the underlying <input type="checkbox"> element.

Disabled

Set the disabled prop of the Checkbox to prevent users from interacting with it.

Indeterminate

Set the indeterminate prop of the Checkbox to true to indicate the Checkbox is neither checked nor unchecked.

A common use case for an indeterminate Checkbox is when the value of a parent Checkbox is dependent on a number of child Checkboxes. The parent Checkbox is set to the indeterminate state if some (but not all) of its children are checked.

Ref Forwarding

Checkbox supports ref forwarding. It will forward ref to its underlying <input type="checkbox"> element.

Label Position

If Form Field is being used, set its labelPosition prop to designate the position of the label relative to the Checkbox. labelPosition accepts the following values:

  • FormField.LabelPosition.Top (Default)
  • FormField.LabelPosition.Left

Required

Set the required prop of a wrapping Form Field to true to indicate that the field is required. Labels for required fields are suffixed by a red asterisk.

Error States

Set the error prop of the wrapping Form Field to FormField.ErrorType.Alert or FormField.ErrorType.Error to set the Checkbox to the Alert or Error state, respectively. You will also need to set the hintId and hintText props on the Form Field to meet accessibility standards. You may wish to omit the label prop on the Form Field given that Checkbox already includes a label.

The error prop may be applied directly to the Checkbox with a value of Checkbox.ErrorType.Alert or Checkbox.ErrorType.Error if Form Field is not being used.

Alert

Alert: You must agree to the terms before proceeding

Error

Error: You must agree to the terms before proceeding

Props

Undocumented props are spread to the underlying <input type="checkbox"> element.

NameTypeDefaultDescription
checkedboolean | undefinedfalseIf true, set the Checkbox to the checked state.
disabledboolean | undefinedfalseIf true, set the Checkbox to the disabled state.
idstring | undefinedA uniquely generated idThe HTML `id` of the underlying checkbox input element. This is required if `label` is defined as a non-empty string.
labelstring | undefined''The text of the Checkbox label.
onChange((e: ChangeEvent<HTMLInputElement>) => void) | undefinedThe function called when the Checkbox state changes.
valuestring | undefinedThe value of the Checkbox.
errorErrorType | undefinedThe type of error associated with the Checkbox (if applicable).
indeterminateboolean | undefinedfalseIf true, set the Checkbox to an indeterminate state. Use this on a Checkbox with nested child Checkboxes to denote that some (but not all) child Checkboxes are checked.
themeEmotionCanvasTheme | undefined
refReact.Ref<any>Optional ref. If the component represents an element, this ref will be a reference to the real DOM element of the component. If `as` is set to an element, it will be that element. If `as` is a component, the reference will be to that component (or element if the component uses `React.forwardRef`).
as"symbol" | "object" | "small" | "a" | "abbr" | "address" | "area" | "article" | "aside" | "audio" | "b" | "base" | "bdi" | "bdo" | "big" | "blockquote" | "body" | "br" | "button" | ... 156 more ... | React.ComponentType<any>Optional override of the default element used by the component. Any valid tag or Component. If you provided a Component, this component should forward the ref using `React.forwardRef` and spread extra props to a root element.

Specifications

GivenWhenThen
given the 'Basic' story is rendered
    • it should not have any axe errors
    given the 'Basic' story is rendered
    • clicked
    • it should be checked
    given the 'Alert' story is rendered
      • it should not have any axe errors
      given the 'Alert' story is rendered
      • clicked
      • it should be checked
      given the 'Error' story is rendered
        • it should not have any axe errors
        given the 'Error' story is rendered
        • clicked
        • it should be checked
        given the 'Disabled' story is rendered
          • it should not have any axe errors
          given the 'Disabled' story is rendered
            • it should be disabled
            Source: Checkbox.spec.ts

            Accessibility Guidelines

            • Groups of Checkboxes should be programmatically grouped together with an associated legend (Form Field Label) or description and each checkbox must have a label.

            Structure

            • <input> tag with attribute type="checkbox" to display a Checkbox.
            • <label> tag with attribute for="CheckboxID" to display a Checkbox Label.

            Visual

            • Avoid using color alone to differentiate between errors and alerts. Instead, use icons or text that says “Error” or “Alert.”
            • If both icons and visible text are used to differentiate between errors and alerts, the icons are considered redundant and should not provide any alternative text for screen readers.
            • When possible, error and alert states should provide information on how to fix issues or hints on fixing formatting.
            • Any Icon Buttons associated with a Checkbox must meet the Non-Text Contrast requirement.
            • Ensure Form Field Label and Checkbox Label exceeds a contrast ratio of 4.5:1 against the background to meet WCAG Success Criterion 1.4.3 for minimum contrast.
            • Ensure keyboard focus is visually indicated and exceeds a contrast ratio of 3.0:1 against the background and prior state to meet WCAG Success Criterion 1.4.11 for non-text contrast.

            Interaction

            • Clicking the Checkbox or Checkbox Label will select or unselect the option.

            Screen Reader

            • Form Field Labels are announced.
            • Checkbox Labels are announced.
            • Checked or unchecked status of Checkboxes are announced.

            Content Guidelines

            • Form Field Labels are written in title case.
            • The Checkbox Label for each individual selection are kept as concise as possible and written in sentence case.
            • When writing Checkbox Labels, refer to the Checkboxes section of the Content Style Guide.

            Can't Find What You Need?

            Check out our FAQ section which may help you find the information you're looking for.

            FAQ Section