Components

Checkbox

The checkbox component is used in forms when a user needs to select multiple values from several options. They may also be used as a way for users to agree to specific terms or opt into a service.

If items are mutually exclusive, use a radio instead.

Import

Checkbox: The checkbox component
CheckboxGroup: A wrapper that groups checkboxes

import { Checkbox, CheckboxGroup } from '@outfitio/outkit';

Usage

CheckboxGroup

The CheckboxGroup component is used to manage the checked state of its children.

You can also display the checkbox group horizontally by passing the isInline prop.

Disabled checkbox

Invalid checkbox

Indeterminate

Indeterminate checkboxes are a user may need to select or deselect all checkboxes within a nested structure.

Checkbox sizes

Pass the size prop to change the size of the Checkbox. Values can be either sm, md or lg.

Accessibility

Screen readers convey the state of the checkbox automatically. The isIndeterminate prop conveys the state of the checkbox using aria-checked="mixed".
Use the disabled prop to apply the HTML disabled attribute to the checkbox input. This prevents users from being able to interact with the checkbox, and conveys its inactive state to assistive technologies.
In the event there is no visible label for the checkbox - for example, within the context of a table column - use the aria-label prop to provide a label for assistive technologies. Alternatively, use aria-labelledby to point to an alternate label.

Best Practice

Checkboxes must work independently from each other. Selecting one checkbox shouldn’t change the selection status of another checkbox in the list, unless the checkbox is used to make a bulk selection of multiple items.
When toggling a setting, checkboxes should correspond to the positive or active state of the setting. For example Turn on notifications instead of Turn off notifications.
Use sentence case for checkbox labels, where the first word is capitalised and the rest are lowercase, unless the term is a proper noun
When within a checkbox group, items should be organised in a logical order, such as alphabetical, numerical, time-based, or another clear system.

Props

Checkbox Props

Name	Type	Default	Description
id	`string`		The id assigned to input field
name	`string`		The name of the input field in a checkbox (Useful for form submission)
value	`string` or `number`		The value to be used in the checkbox input. This is the value that will be returned on form submission.
variantColor	`string`		The color of the checkbox when it's checked. This should be one of the color keys in the theme (e.g."green", "red")
defaultIsChecked	`boolean`		If `true`, the checkbox will be initially checked.
isChecked	`boolean`		If `true`, the checkbox will be checked. You'll need to pass `onChange` to update it's value (since it's now controlled)
isIndeterminate	`boolean`		If `true`, the checkbox will be indeterminate. This only affects the icon shown inside checkbox
isFullWidth	`boolean`		If `true`, the checkbox should take up the full width of the parent.
size	`sm`, `md`, `lg`	`md`	The size (width and height) of the checkbox
isDisabled	`boolean`		If `true`, the checkbox will be disabled
isInvalid	`boolean`		If `true`, the checkbox is marked as invalid. Changes style of unchecked state.
children	`React.ReactNode`		The children of the checkbox.
onChange	`function`		Function called when the state of the checkbox changes.
onBlur	`function`		Function called when you blur out of the checkbox.
onFocus	`function`		Function called when the checkbox receive focus.
aria-label	`string`		An accessible label for the checkbox in event there's no visible label or `children` passed
aria-labelledby	`string`		Id that points to the label for the checkbox in event no `children` was passed

CheckboxGroup Props

CheckboxGroup composes Box so you can pass all Box props.

Name	Type	Default	Description
id	`string`		The id of the checkbox group.
name	`string`		The name of the checkbox group. This attribute is
value	`Array<Checkbox["value"]>`		The value of the checkbox group
defaultValue	`Array<Checkbox["value"]>`		The initial value of the checkbox group
variantColor	`string`		The color of the checkbox when it's checked. This should be one of the color keys in the theme (e.g."green", "red")
onChange	`(values: Array<Checkbox["value"]>): void`		The callback fired when any children Checkbox is checked or unchecked
children	`React.ReactNode`		The content of the checkbox group. Must be the `Checkbox` component
spacing	`StyledSystem.MarginProps`	`8px`	The space between each checkbox
size	`sm`, `md`, `lg`	`md`	The size of the checkbox, it's forwarded to all children checkbox.
isInline	`boolean`		If `true`, the checkboxes will aligned horizontally.