# Checkbox > Checkbox is an input control that lets users select one or more options from a list of options. ## Import ```js import { Checkbox, CheckboxGroup } from '@gemini-suite/vera-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](/components/switch) instead. One exception to this guideline is using checkboxes as page-level filters that take effect immediately. ```jsx {'Unchecked'} {'Checked'} {'Indeterminate'} {'Disabled'} {'Checked + disabled'} ``` ### Controlled It is most common to set up `Checkbox` as a [controlled component](https://reactjs.org/docs/forms.html#controlled-components), 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. ```jsx () => { const [isChecked, setIsChecked] = React.useState(false); const handleChange = event => setIsChecked(event.target.checked); return ( {'Controlled'} ); }; ``` ### 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. ```jsx () => { const [checkedItems, setCheckedItems] = React.useState([false, false]); const everyChecked = checkedItems.every(Boolean); const isIndeterminate = checkedItems.some(Boolean) && !everyChecked; return ( setCheckedItems([e.target.checked, e.target.checked])} > {'All ingredients'} setCheckedItems([e.target.checked, checkedItems[1]])} > {'Ingredient 1'} setCheckedItems([checkedItems[0], e.target.checked])} > {'Ingredient 2'} ); }; ``` ### 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". ```jsx Enable notifications We will not send any notifications to your account when turned off. ``` ### 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. ```jsx console.log(val)} > {'Bulbasaur'} {'Charmander'} {'Squirtle'} ``` Mark the checkbox group as disabled by passing `true` to the `isDisabled` prop. All descendant inputs will be disabled. ```jsx {'Bulbasaur'} {'Charmander'} {'Squirtle'} ``` ### With Form Field [Form Field component](/components/forms/form-field) 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 `` element. The `as` prop should be provided with another element type, such as `span`. ```jsx How do you like your eggs? Select all the options that apply Overeasy Hard-boiled Scram-boiled A hardboiled egg that is then scrambled ``` Don't validate each checkbox in a group, always treat validation on the group as a whole. ```jsx () => { const [groupValue, setGroupValue] = React.useState([]); return ( Choose ingredients {'Tomato'} {'Lettuce'} {'Cucumber'} {'You must choose at least one ingredient.'} ); }; ``` Checkboxes in a field group should be listed in a logical order (alphabetical, numerical, time-based, etc). ```jsx Choose preferred days Monday Tuesday Wednesday Thursday Friday ``` ### 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. ```jsx Label ``` Alternatively, you may provide `aria-label` property to maintain accessibility: ```jsx ``` ### Sizes `Checkbox` component comes in two different sizes: `medium` and `small`. By default, it uses `medium` size. ```jsx {'Default'} Extra information. {'Small'} Extra information. ``` #### Size inheritance `Checkbox` automatically inherits size, when placed inside a [FormField component](/components/forms/form-field). ```jsx Choose preferred days Select all the options that apply Overeasy Hard-boiled Scram-boiled A hardboiled egg that is then scrambled Choose preferred days Select all the options that apply Overeasy Hard-boiled Scram-boiled A hardboiled egg that is then scrambled ``` ### Customizing appearance `Checkbox` API allows you to easily implement custom behaviours and appearances. ```jsx () => { const [groupValue, setGroupValue] = React.useState([]); const customStyles = { borderRadius: '$m', padding: '$spacingM', border: '1px solid $borderNeutralSubtle' }; return ( Choice A Label Extra information about the choice A Choice B Label Extra information about the choice B ); }; ``` --- ## API Reference ### Checkbox.Root In addition to the props below, you can pass [Flex props](/components/layout/flex#api-reference) to control the layout. | Name | Type | Default | Description | Required | | ------------------ | --------------------------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | `as` | `keyof JSX.IntrinsicElements \| React.ComponentType` | `div` | Change the component to a different HTML tag or custom component. This will merge the original component props with the props of the supplied element/component and change the underlying DOM node. For more details, read our [Composition](/get-started/composition#polymorphism) guide. | | | `css` | `StitchesCss` | | Apply styles directly to a component in a similar way how you would define inline styles. Vera uses [Stitches](https://stitches.dev/) under the hood with a fully-typed API and support for features like tokens, media queries, or variants. | | | `value` | `string \| number` | | The value to be used in the checkbox input. It will be returned on form submission. | | | `name` | `string` | | Name attribute of the input field in a checkbox. Useful for form submission. | | | `id` | `string` | | ID assigned to input. Used for `htmlFor` of `Checkbox.Label`. Defaults to a generated ID. | | | `defaultChecked` | `boolean` | `false` | When `true` the checkbox will be initially checked. | | | `isChecked` | `boolean` | | When `true`, the checkbox will be checked. This makes the checkbox controlled, so passing `onChange` is required to update its value. | | | `onChange` | `(event: React.ChangeEvent) => void` | | Event handler called when the input checked state changes. | | | `onFocus` | `(event: React.FocusEvent) => void` | | Event handler called when the input receives a focus. | | | `onBlur` | `(event: React.FocusEvent) => void` | | Event handler called when focus has left the input. | | | `isIndeterminate` | `boolean` | | When `true`, the checkbox will be indeterminate. This only affects the style of the checkbox and does not modify the `isChecked` property. | | | `isDisabled` | `boolean` | | When `true`, the checkbox will be disabled, preventing the user from interacting with it. | | | `isReadOnly` | `boolean` | | When `true`, the checkbox will be readonly. | | | `isRequired` | `boolean` | | When `true`, the checkbox input is marked as required. | | | `validationStatus` | `"error" \| "success" \| "warning"` | | Styles the checkbox to match the status. | | | `size` | `"medium" \| "small"` | | Size of the checkbox. | | ### Checkbox.Indicator | Name | Type | Default | Description | Required | | ----- | ------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | `css` | `StitchesCss` | | Apply styles directly to a component in a similar way how you would define inline styles. Vera uses [Stitches](https://stitches.dev/) under the hood with a fully-typed API and support for features like tokens, media queries, or variants. | | ### Checkbox.Label | Name | Type | Default | Description | Required | | ----- | --------------------------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | `as` | `keyof JSX.IntrinsicElements \| React.ComponentType` | `label` | Change the component to a different HTML tag or custom component. This will merge the original component props with the props of the supplied element/component and change the underlying DOM node. For more details, read our [Composition](/get-started/composition#polymorphism) guide. | | | `css` | `StitchesCss` | | Apply styles directly to a component in a similar way how you would define inline styles. Vera uses [Stitches](https://stitches.dev/) under the hood with a fully-typed API and support for features like tokens, media queries, or variants. | | ### Checkbox.HelperText In addition to the props below, you can pass [Text props](/components/typography/text#api-reference). | Name | Type | Default | Description | Required | | ----- | ------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | `css` | `StitchesCss` | | Apply styles directly to a component in a similar way how you would define inline styles. Vera uses [Stitches](https://stitches.dev/) under the hood with a fully-typed API and support for features like tokens, media queries, or variants. | | ### CheckboxGroup | Name | Type | Default | Description | Required | | -------------- | --------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------- | -------- | | `defaultValue` | `(string \| number)[]` | | The initial value of the checkbox group | | | `value` | `(string \| number)[]` | | Value of the checkbox group. This makes the group controlled, so passing `onChange` is required to update the value. | | | `onChange` | `(value: (string \| number)[]) => void` | | Event handler called when any children `Checkbox` is checked or unchecked. | | | `isDisabled` | `boolean` | | When `true`, all checkbox inputs within the group will be disabled. | |