1. Components
  2. Forms and inputs
  3. Checkbox

Checkbox

Checkboxes allow users to select multiple items from a list of individual items, or to mark one individual item as selected.

<Checkbox>I accept the <Link href="/terms">terms and conditions</Link></Checkbox>

Installation

npx dotui-cli@latest add checkbox

Usage

Use Checkbox to allow users to select multiple items from a list of individual items, or to mark one individual item as selected.

import { Checkbox } from "@/components/core/checkbox";
 
<Checkbox>I accept the terms and conditions</Checkbox>;
import { CheckboxRoot, CheckboxIndicator } from "@/components/core/checkbox";
 
<CheckboxRoot>
  <span>I accept the terms and conditions</span>
  <CheckboxIndicator />
</CheckboxRoot>;

Options

Variants

Use the variant prop to control the visual style of the checkbox.

<Checkbox variant="card">I accept the terms and conditions</Checkbox>

Appearance

You can make the checkbox appear as a card using the appearance prop.

<Checkbox variant="card">I accept the terms and conditions</Checkbox>

Indeterminate

A checkbox can be in an indeterminate state, controlled using the isIndeterminate prop.

<Checkbox isIndeterminate>Select all</Checkbox>

Disabled

Use the isDisabled prop to disable the checkbox.

<Checkbox isDisabled>I accept the terms and conditions</Checkbox>

Read only

The isReadOnly prop makes the selection immutable. Unlike isDisabled, the Checkbox remains focusable.

<Checkbox isReadOnly>I accept the terms and conditions</Checkbox>

Composition

If you need to customize things further, you can drop down to the composition level.

<CheckboxRoot className="..">
  <span>I agree to the terms and conditions</span>
  <CheckboxIndicator className=".."/>
</CheckboxRoot>

Uncontrolled

The defaultSelected prop can be used to set the default state.

<Checkbox defaultSelected>I accept the terms and conditions</Checkbox>

Controlled

Use the isSelected and onChange props to control the value of the input.

Checked: false

const [checked, setChecked] = React.useState(false);
return (
  <Checkbox isSelected={checked} onChange={setChecked}>
    I accept the terms and conditions
  </Checkbox>
);

API Reference

PropTypeDefaultDescription
variant"default" | "card""default"The visual style of the checkbox group.
inputRefMutableRefObject<HTMLInputElement>-A ref for the HTML input element.
isIndeterminateboolean-Indeterminism is presentational only. The indeterminate visual representation remains regardless of user interaction.
defaultSelectedboolean-Whether the element should be selected (uncontrolled).
isSelectedboolean-Whether the element should be selected (controlled).
valuestring-The value of the input element, used when submitting an HTML form.
isDisabledboolean-Whether the input is disabled.
isReadOnlyboolean-Whether the input can be selected but not changed by the user.
isRequiredboolean-Whether user input is required on the input before form submission.
isInvalidboolean-Whether the input value is invalid.
validate(value: boolean) => ValidationError| true| null| undefined-A function that returns an error message if a given value is invalid. Validation errors are displayed to the user when the form is submitted if validationBehavior="native". For realtime validation, use the isInvalid prop instead.
autoFocusboolean-Whether the element should receive focus on render.
namestring-The name of the input element, used when submitting an HTML
validationBehavior'native' | 'aria''native'Whether to use native HTML form validation to prevent form submission when the value is missing or invalid, or mark the field as required or invalid via ARIA.
childrenReactNode | (values: CheckboxRenderProps & {defaultChildren: ReactNode | undefined}) => ReactNode-The children of the component. A function may be provided to alter the children based on component state.
classNamestring-The CSS className for the element.
styleCSSProperties | (values: CheckboxRenderProps & {defaultStyle: CSSProperties}) => CSSProperties-The inline style for the element. A function may be provided to compute the style based on component state.
EventTypeDescription
onChange(isSelected: boolean) => voidHandler that is called when the element's selection state changes.
onFocus(e: FocusEvent<Target>) => voidHandler that is called when the element receives focus.
onBlur(e: FocusEvent<Target>) => voidHandler that is called when the element loses focus.
onFocusChange(isFocused: boolean) => voidHandler that is called when the element's focus status changes.
onKeyDown(e: KeyboardEvent) => voidHandler that is called when a key is pressed.
onKeyUp(e: KeyboardEvent) => voidHandler that is called when a key is released.
onHoverStart(e: HoverEvent) => voidHandler that is called when a hover interaction starts.
onHoverEnd(e: HoverEvent) => voidHandler that is called when a hover interaction ends.
onHoverChange(isHovering: boolean) => voidHandler that is called when the hover state changes.
Data attributeDescription
[data-selected]Whether the checkbox is selected.
[data-indeterminate]Whether the checkbox is indeterminate.
[data-hovered]Whether the checkbox is currently hovered with a mouse.
[data-pressed]Whether the checkbox is currently in a pressed state.
[data-focused]Whether the checkbox is focused, either via a mouse or keyboard.
[data-focus-visible]Whether the checkbox is keyboard focused.
[data-disabled]Whether the checkbox is disabled.
[data-readonly]Whether the checkbox is read only.
[data-invalid]Whether the checkbox invalid.
[data-required]Whether the checkbox is required.

Accessibility

Keyboard interactions

KeyDescription
SpaceToggles the checkbox between selected and not selected

Built by mehdibha. The source code is available on GitHub.