Checkbox

Best Practices

• Use checkboxes to turn an option on or off for multiple options appearing in a list.
• If you have a single option, avoid using a checkbox and use EzToggle instead.
• Checkboxes should be clearly labelled, or provided an accessible name.
• Checkboxes should not be used to perform actions.
• Clicking a checkbox should not persist until a separate action button is clicked (ex. form submission).
• Options should be structured in a logical order, such as from simplest to most complex, or most common to least common.

Examples

Basic Checkboxes

EzCheckbox supports outlined (default), filled (for darker backgrounds), and filled-inverse variants.

To mark the checkbox as checked by default, use the defaultChecked prop.

Checkbox Labels

To add a label to a checkbox, use EzFormControlLabel and provide the EzCheckbox to its control prop along with the label.

You can optionally append a set of icons to the label by passing in an array of EzIcons to labelIcons in EzFormControlLabel.

Checkbox Colors

EzCheckbox supports theme palette properties (primary, secondary, error, warning, info, alert, neutral, and success) as well as all supported theme colors (ex. common.red100). Colors should have high enough contrast for accessibility.

Checkbox Sizes

If you want to specify a size, use the size property. We currently support small, medium (default), and large.

Checkbox Indeterminate State

A checkbox input has only one of two states: checked or unchecked. However, visually, a checkbox can also have an indeterminate state by using the indeterminate property on EzCheckbox.

Checkbox Group

EzCheckbox components can be grouped using form controls (see below).

• To define the gap between checkbox labels, use the optional gap prop of type number on EzFormGroup.

  • Recipe uses an 8px scaling factor, so a gap of x (of type number) is equal to x * 8px.
  • The default gap for columns is 0 and rows is 2.
• To lay out the buttons horizontally, use the optional row prop on EzFormGroup.
• To add helper text to a checkbox label, use the optional helperText prop on EzFormControlLabel.

Checkbox Controlled Group

You can also control the checkbox with the checked prop on EzFormControlLabel and onChange on EzCheckbox.

Checkbox Group with Conditional Content

Additional content can also be displayed depending on the selection.

Checkbox Group with Error State

To display an error state in a checkbox group, pass an error boolean property to EzFormControl. Be sure to include an error alert or message to indicate what the error is.

To provide proper keyboard accessibility when using checkboxes, use EzCheckbox with the following components and their props:

• EzFormControl - used to provide context and ensure a consistent state

  • error - if true, the label is displayed in an error state
  • fullWidth - if true, the component will take up the full width of its container

• EzFormLabel - used to provide a label for a group of checkboxes

  • id - should match the ariaLabel prop of EzFormGroup

• EzFormGroup - used to group checkboxes

  • ariaLabel - should match the id prop of EzFormLabel
  • gap - the gap between form labels (defaults to 0 for columns and 2 for rows)
  • row - lays out the checkboxes horizontally
  • labelWidth - the defined width of each super checkbox button in a form group
  • theme - a defined theme object with optional keys color and variant for super checkbox buttons

• EzFormControlLabel - used to provide a label for a checkbox

  • control - the required control element (<EzCheckbox />)
  • disabled - if true, the component is disabled
  • helperText - the helper text content
  • icon - the icon for the checkbox when using a super checkbox
  • label - the label for the checkbox
  • labelIcons - an optional array of EzIcons to display after the label
  • value - the value of the form control label

Super Checkbox Buttons

For larger, more visual checkbox buttons, provide an icon (<EzIcon />) along with an optional label to EzFormControlLabel.

• To define a set pixel width for the buttons, pass a labelWidth of type number to EzFormGroup. Labels will wrap if needed, but should not be more than 2 lines.

• To define a theme for each button in a group, pass a theme property to EzFormGroup.

  • color accepts either a color theme property (ex. color: 'primary'), or a custom defined values object (see example below)
  • variant accepts either filled (default), or outlined (filled-inverse is not supported - use custom defined values)
• Super checkbox buttons must be controlled, so be sure to pass checked and value properties to EzFormControlLabel as well as onChange to EzCheckbox.

Disabled Checkboxes

A checkbox can be made disabled by adding the optional disabled prop on either EzCheckbox (if standalone) or EzFormControlLabel (if in a group).

Custom Styles

Supported styles should be used, but if you need to overwrite styles for the checkbox, form label, or form control label, you can do so using provided class names:

• EzCheckbox, EzCheckbox-outlined, EzCheckbox-filled, EzCheckbox-filled-inverse, EzCheckbox-checked, EzCheckbox-unchecked, EzCheckbox-indeterminate, EzCheckbox-icon, EzCheckbox-disabled, EzCheckbox-input
• EzFormGroup
• EzFormLabel
• EzFormControlLabel, EzFormControlLabel-label, EzFormControlLabel-helperText
• EzSuperFormControlLabel, EzSuperFormControlLabel-checkbox, EzSuperFormControlLabel-checked, EzSuperFormControlLabel-label,EzSuperFormControlLabel-icon, EzSuperFormControlLabel-text

Accessibility

See WAI-ARIA accessibility guidelines for checkboxes.

All checkbox form controls should have corresponding labels using ariaLabel (hidden) or EzFormControlLabel.

Checkboxes should also have a name property, which is used to set or return the value of the named attribute of the checkbox field.

Props

Related components

• EzField
• EzRadio
• EzToggle