Checkbox

Anatomy

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.

import React from 'react';
import {Checkbox} from '@workday/canvas-kit-react/checkbox';
import {FormField} from '@workday/canvas-kit-react/form-field';

export default () => {
  const [checked, setChecked] = React.useState(false);

  const handleChange = (event: React.ChangeEvent<HTMLInputElement>) => {
    setChecked(event.target.checked);
  };

  return (
    <FormField>
      <FormField.Label>Confirm</FormField.Label>
      <FormField.Field>
        <FormField.Input
          as={Checkbox}
          checked={checked}
          label="I agree to the terms"
          onChange={handleChange}
        />
      </FormField.Field>
    </FormField>
  );
};

Inverse

Checkbox with inverse variation

import React from 'react';
import {Checkbox} from '@workday/canvas-kit-react/checkbox';
import {Flex} from '@workday/canvas-kit-react/layout';
import {createStyles} from '@workday/canvas-kit-styling';
import {system} from '@workday/canvas-tokens-web';

const styleOverrides = createStyles({
  backgroundColor: system.color.bg.primary.default,
  padding: system.space.x4,
});

export default () => {
  const [checked, setChecked] = React.useState(false);

  const handleChange = (event: React.ChangeEvent<HTMLInputElement>) => {
    setChecked(event.target.checked);
  };

  return (
    <Flex cs={styleOverrides}>
      <Checkbox
        variant="inverse"
        checked={checked}
        label="I agree to the terms"
        onChange={handleChange}
      />
    </Flex>
  );
};

Disabled

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

import React from 'react';
import {Checkbox} from '@workday/canvas-kit-react/checkbox';
import {FormField} from '@workday/canvas-kit-react/form-field';

export default () => {
  const [checked, setChecked] = React.useState(false);

  const handleChange = (event: React.ChangeEvent<HTMLInputElement>) => {
    setChecked(event.target.checked);
  };

  return (
    <FormField>
      <FormField.Label>Confirm</FormField.Label>
      <FormField.Field>
        <FormField.Input
          as={Checkbox}
          checked={checked}
          disabled={true}
          label="I agree to the terms"
          onChange={handleChange}
        />
      </FormField.Field>
    </FormField>
  );
};

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.

import React from 'react';
import {Checkbox} from '@workday/canvas-kit-react/checkbox';
import {Box} from '@workday/canvas-kit-react/layout';
import {createStyles} from '@workday/canvas-kit-styling';
import {system} from '@workday/canvas-tokens-web';

const styleOverrides = createStyles({
  marginInlineLeft: system.space.x8,
  marginTop: system.space.x2,
});

export default () => {
  const [pizzaChecked, setPizzaChecked] = React.useState(false);
  const [pizzaIndeterminate, setPizzaIndeterminate] = React.useState(false);

  const [toppings, setToppings] = React.useState([
    {name: 'Pepperoni', checked: false},
    {name: 'Sausage', checked: false},
    {name: 'Bell Peppers', checked: false},
    {name: 'Olives', checked: false},
    {name: 'Onions', checked: false},
  ]);

  const handlePizzaChange = (event: React.ChangeEvent<HTMLInputElement>) => {
    const checked = event.target.checked;

    if (checked || (!checked && pizzaIndeterminate)) {
      setPizzaChecked(true);
      setToppings(
        toppings.map(topping => ({
          ...topping,
          checked: true,
        }))
      );
    } else {
      setPizzaChecked(false);
      setToppings(
        toppings.map(topping => ({
          ...topping,
          checked: false,
        }))
      );
    }

    setPizzaIndeterminate(false);
  };

  const handleToppingChange = (event: React.ChangeEvent<HTMLInputElement>, index: number) => {
    const newToppings = toppings.map(topping => ({...topping}));
    newToppings[index].checked = event.target.checked;
    setToppings(newToppings);

    const anyToppingChecked = newToppings.filter(topping => topping.checked).length > 0;
    const anyToppingUnchecked = newToppings.filter(topping => !topping.checked).length > 0;
    const allToppingChecked = !anyToppingUnchecked;
    setPizzaIndeterminate(anyToppingChecked && anyToppingUnchecked);
    setPizzaChecked(allToppingChecked);
  };

  return (
    <>
      <Checkbox
        checked={pizzaChecked}
        indeterminate={pizzaIndeterminate}
        label="Supreme Pizza Toppings"
        onChange={handlePizzaChange}
      />
      <Box cs={styleOverrides}>
        {toppings.map((topping, index) => (
          <Checkbox
            checked={topping.checked}
            key={topping.name}
            label={topping.name}
            onChange={event => handleToppingChange(event, index)}
          />
        ))}
      </Box>
    </>
  );
};

Ref Forwarding

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

import React from 'react';
import {PrimaryButton} from '@workday/canvas-kit-react/button';
import {Checkbox} from '@workday/canvas-kit-react/checkbox';
import {Box} from '@workday/canvas-kit-react/layout';
import {system} from '@workday/canvas-tokens-web';
import {createStyles, px2rem} from '@workday/canvas-kit-styling';
import {FormField} from '@workday/canvas-kit-react/form-field';

const boxStyles = createStyles({
  display: 'flex',
  flexDirection: 'column',
});

export default () => {
  const [checked, setChecked] = React.useState(false);
  const ref = React.useRef(null);

  const handleChange = (event: React.ChangeEvent<HTMLInputElement>) => {
    setChecked(event.target.checked);
  };

  const handleClick = () => {
    ref.current.click();
  };

  return (
    <>
      <Box cs={boxStyles}>
        <FormField>
          <FormField.Label>Confirm</FormField.Label>
          <FormField.Field>
            <FormField.Input
              as={Checkbox}
              checked={checked}
              label="I agree to the terms"
              onChange={handleChange}
              ref={ref}
            />
          </FormField.Field>
        </FormField>
      </Box>
      <PrimaryButton onClick={handleClick}>Check Agreement to Terms</PrimaryButton>
    </>
  );
};

Label Position Horizontal

Set the orientation prop of the Form Field to designate the position of the label relative to the input component. By default, the orientation will be set to vertical.

import React from 'react';
import {Checkbox} from '@workday/canvas-kit-react/checkbox';
import {FormField} from '@workday/canvas-kit-react/form-field';

export default () => {
  const [checked, setChecked] = React.useState(false);

  const handleChange = (event: React.ChangeEvent<HTMLInputElement>) => {
    setChecked(event.target.checked);
  };

  return (
    <FormField orientation="horizontalStart">
      <FormField.Label>Confirm</FormField.Label>
      <FormField.Field>
        <FormField.Input
          as={Checkbox}
          checked={checked}
          label="I agree to the terms"
          onChange={handleChange}
        />
      </FormField.Field>
    </FormField>
  );
};

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.

import React from 'react';
import {Checkbox} from '@workday/canvas-kit-react/checkbox';
import {FormField} from '@workday/canvas-kit-react/form-field';

export default () => {
  const [checked, setChecked] = React.useState(false);

  const handleChange = (event: React.ChangeEvent<HTMLInputElement>) => {
    setChecked(event.target.checked);
  };

  return (
    <FormField isRequired={true}>
      <FormField.Label>Confirm</FormField.Label>
      <FormField.Field>
        <FormField.Input
          as={Checkbox}
          checked={checked}
          label="I agree to the terms"
          onChange={handleChange}
        />
      </FormField.Field>
    </FormField>
  );
};

Error States

Set the error prop of the wrapping Form Field to "caution" or "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 "caution" or "error" if Form Field is not being used.

Caution

import React from 'react';
import {Checkbox} from '@workday/canvas-kit-react/checkbox';
import {FormField} from '@workday/canvas-kit-react/form-field';

export default () => {
  const [checked, setChecked] = React.useState(false);

  const handleChange = (event: React.ChangeEvent<HTMLInputElement>) => {
    setChecked(event.target.checked);
  };

  return (
    <FormField error="caution">
      <FormField.Label>Confirm</FormField.Label>
      <FormField.Field>
        <FormField.Input
          as={Checkbox}
          checked={checked}
          label="I agree to the terms"
          onChange={handleChange}
        />
        <FormField.Hint>You must agree to the terms before proceeding</FormField.Hint>
      </FormField.Field>
    </FormField>
  );
};

Error

import React from 'react';
import {Checkbox} from '@workday/canvas-kit-react/checkbox';
import {FormField} from '@workday/canvas-kit-react/form-field';

export default () => {
  const [checked, setChecked] = React.useState(false);

  const handleChange = (event: React.ChangeEvent<HTMLInputElement>) => {
    setChecked(event.target.checked);
  };

  return (
    <FormField error="error">
      <FormField.Label>Confirm</FormField.Label>
      <FormField.Field>
        <FormField.Input
          as={Checkbox}
          checked={checked}
          label="I agree to the terms"
          onChange={handleChange}
        />
        <FormField.Hint>You must agree to the terms before proceeding</FormField.Hint>
      </FormField.Field>
    </FormField>
  );
};

Custom Styles

Checkbox supports custom styling via the cs prop. For more information, check our “How To Customize Styles”.

Component API

import {handleCsProp} from '@workday/canvas-kit-styling';
import {mergeStyles} from '@workday/canvas-kit-react/layout';

// ...

// `handleCsProp` handles compat mode with Emotion's runtime APIs. `mergeStyles` has the same
// function signature, but adds support for style props.

return (
 <Element
   {...handleCsProp(elemProps, [
     myStyles,
     myModifiers({ size: 'medium' }),
     myVars({ backgroundColor: 'red' })
   ])}
 >
   {children}
 </Element>
)

ErrorType

Specifications

Accessibility Guidelines

How Checkboxes Impact the Accessible Experience

Checkboxes used to present a group of choices require context, such as, selecting your pizza toppings. Designing a clear legend and building the context of the group is a key foundation for accessible checkboxes when users cannot visually perceive the layout.

Keyboard Interaction

Each Checkbox must have a focus indicator that is highly visible against the background and against the non-focused state. Refer to Accessible Colors for more information.

Checkboxes must support the following keyboard interactions:

• Tab: focus a checkbox
• Space: select/unselect a focused checkbox

Screen Reader Interaction

Checkboxes must communicate the following to users:

• The name (Form Field Label) of the checkbox grouping, if applicable
• The accessible name (label) of the focused checkbox
• Whether the checkbox is selected or unselected

Design Annotations Needed

• Write the context (legend) of the checkbox grouping, if applicable.

Implementation Markup Needed

• Checkbox must have a required attribute when the Checkbox is required for submission.
• Checkbox must have an aria-invalid=”true” attribute when it has an error condition.
• [Included in component] A <label> element is required with a for attribute referencing the unique id value of the associated Checkbox.
• [Included in component] A <fieldset> element establishes the group of related Checkboxes. The child <legend> element describes the context of the grouping.
• [Included in component] A disabled attribute is set when the Checkbox is disabled.

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.

Anatomy

1. Container: Main container of the Checkbox
2. Checkmark: System icon used to indicate if the item is selected or unselected.
3. Checkbox Label: Checkbox Labels give information about what to select or unselect.

Interaction States

Mobile checkboxes support the Inactive, Pressed, Selected, and Disabled states.

Usage Guidance

• Checkbox Labels are positioned to the right of the Checkbox for LTR languages or to the left of Checkbox for RTL languages.
• Checkboxes allow users to select one or many options. Selected options are shown as a white check with blue fill. Tapping it again will deselect the choice.
• Each Checkbox is tied to a distinct value. Labels for each selection should describe the choice and be kept as concise as possible. Please reference the Checkbox section of the Content style guide 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 for binary options such as yes/no or active/disabled.
• Use a Radio Button to select a single option from a list of 2 to 7 options.
• 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.

Mobile Guidance

• Ensure a minimum tap target of 48dp to ensure that Checkboxes are easy to interact with.
• For Checkboxes, an additional 12dp of tappable horizontal and vertical padding are added to meet the minimum touch target.

API Guidelines

Component Definition

Checkbox

public struct Checkbox: View

WD-Standard Checkbox component, a custom SwiftUI view. This can be either a compound checkbox (re: CheckboxInput) or a simple checkbox with associated text, depending on the params sent. Checkbox is a custom view to meet accessibility needs for this component.

Properties

body

public var body: some View

Methods

init(_:label:helperText:isSelected:context:accessibilityLabel:)

public init(
    _ text: String = "",
    label: String = "",
    helperText: String? = nil,
    isSelected: Binding<Bool>,
    context: SemanticContext = .default,
    accessibilityLabel: String = ""
)

Creates an instance of Checkbox, applying a pre-computed accessibilityLabel.

Parameters

init(_:label:helperText:isSelected:context:localizer:)

public init(
    _ text: String = "",
    label: String = "",
    helperText: String? = nil,
    isSelected: Binding<Bool>,
    context: SemanticContext = .default,
    localizer: LocalizationAdapting
)

Creates an instance of Checkbox, with default accessibility behavior when provided a localizer.

Parameters

Accessibility Guidelines

Refreshed mobile guidelines will be coming soon!

Content Guidelines

• The Checkbox Label for each individual selection is kept as concise as possible, and written in sentence case.
• When writing Checkbox labels, refer to the Checkbox section of the Content Style Guide.

Anatomy

1. Container: Main container of the Checkbox
2. Checkmark: System icon used to indicate if the item is selected or unselected.
3. Checkbox Label: Checkbox Labels give information about what to select or unselect.

Interaction States

Mobile checkboxes support the Inactive, Pressed, Selected, and Disabled states.

Usage Guidance

• Checkbox Labels are positioned to the right of the Checkbox for LTR languages or to the left of Checkbox for RTL languages.
• Checkboxes allow users to select one or many options. Selected options are shown as a white check with blue fill. Tapping it again will deselect the choice.
• Each Checkbox is tied to a distinct value. Labels for each selection should describe the choice and be kept as concise as possible. Please reference the Checkbox section of the Content style guide 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 for binary options such as yes/no or active/disabled.
• Use a Radio Button to select a single option from a list of 2 to 7 options.
• 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.

Mobile Guidance

• Ensure a minimum tap target of 48dp to ensure that Checkboxes are easy to interact with.
• For Checkboxes, an additional 12dp of tappable horizontal and vertical padding are added to meet the minimum touch target.

API Guidelines

Component Definition

@Composable
fun RadioButtonUiComponent(
    modifier: Modifier = Modifier,
    checked: Boolean,
    onCheckedChange: (Boolean) -> Unit?,
    enabled: Boolean = true,
    interactionSource: MutableInteractionSource = remember { MutableInteractionSource() },
    semanticState: SemanticState = SemanticState(),
    colors: CheckboxColors = CheckboxDefaults.colors())
) {

Parameters

Accessibility Guidelines

Refreshed mobile guidelines will be coming soon!

Content Guidelines

• The Checkbox Label for each individual selection is kept as concise as possible, and written in sentence case.
• When writing Checkbox labels, refer to the Checkbox section of the Content Style Guide.