Checkbox

Checkbox is an input control that lets users select one or more options from a list of options.

Import#

import { Checkbox, CheckboxGroup } from '@volue/wave-react';

Examples#

Basic#

Use Checkbox when selection doesn’t take immediate effect (typically within a form that requires submission). To turn a state on and off with immediate effect such as enabling or disabling a system feature, consider using Switch instead.

One exception to this guideline is using checkboxes as page-level filters that take effect immediately.

Controlled#

It is most common to set up Checkbox as a controlled component, meaning that React state drives its value. To achieve this you must provide isChecked and onChange properties.

The defaultChecked prop will have no effect in a controlled checkbox.

Indeterminate state#

Use isIndeterminate prop to convey that a checkbox is partially checked and controls a set of sub-checkboxes. In the following example, the checkbox is indeterminate when not every descendant is checked.

Checkbox with help text#

In cases where the checkbox requires additional context, you can display this information as help text. This helps keep checkbox labels concise.

Avoid lengthy text labels. Be clear and brief with checkbox labels so they are easily scanned. Label things positively. For example, prefer "Enable notifications" over "Don't send me notifications".

CheckboxGroup#

Multiple checkboxes and their labels should be grouped together with a common CheckboxGroup component.

CheckboxGroup helps managing the checked state of its children Checkbox components and conveniently passes some shared props to each.

Make sure to pass value prop to each checkbox within a group.

Mark the checkbox group as disabled by passing true to the isDisabled prop. All descendant inputs will be disabled.

With Form Field#

Form Field component should be used to label groups of related checkboxes. The same goes for connecting helper text and/or validation feedback message.

When providing a top-level label for a group of checkbox inputs that are already labelled, it doesn't make sense for the FormField.Label to render an HTML <label> element. The as prop should be provided with another element type, such as span.

Don't validate each checkbox in a group, always treat validation on the group as a whole.

Checkboxes in a field group should be listed in a logical order (alphabetical, numerical, time-based, etc).

Standalone checkbox#

In some rare cases, you may need to render a standalone checkbox. Make sure to always associate the checkbox with a label and make the label visually hidden. A standalone checkbox without an accessible label does not describe its purpose.

Alternatively, you may provide aria-label property to maintain accessibility:

Sizes#

Checkbox component comes in two different sizes: medium and small. By default, it uses medium size.

Size inheritance#

Checkbox automatically inherits size, when placed inside a FormField component.

Customizing appearance#

Checkbox API allows you to easily implement custom behaviours and appearances.

API Reference#

Checkbox.Root#

In addition to the props below, you can pass Flex props to control the layout.

Prop	Type	Default
`as`	`enum`	`div`
`css`	`StitchesCss`	No default value
`value`	`string \| number`	No default value
`name`	`string`	No default value
`id`	`string`	No default value
`defaultChecked`	`boolean`	`false`
`isChecked`	`boolean`	No default value
`onChange`	`function`	No default value
`onFocus`	`function`	No default value
`onBlur`	`function`	No default value
`isIndeterminate`	`boolean`	No default value
`isDisabled`	`boolean`	No default value
`isReadOnly`	`boolean`	No default value
`isRequired`	`boolean`	No default value
`validationStatus`	`enum`	No default value
`size`	`enum`	No default value

Checkbox.Indicator#

Prop	Type	Default
`css`	`StitchesCss`	No default value

Checkbox.Label#

Prop	Type	Default
`as`	`enum`	`label`
`css`	`StitchesCss`	No default value

Checkbox.HelperText#

In addition to the props below, you can pass Text props.

Prop	Type	Default
`css`	`StitchesCss`	No default value

CheckboxGroup#

Prop	Type	Default
`defaultValue`	`(string \| number)[]`	No default value
`value`	`(string \| number)[]`	No default value
`onChange`	`function`	No default value
`isDisabled`	`boolean`	No default value