Checkbox

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

Storybook @nextui-org/checkbox React Aria Source Styles source

Installation

nextui add checkbox

No need to install this package if @nextui-org/react is already installed globally.

Import

Usage

Disabled

Sizes

Colors

Radius

Indeterminate

The isIndeterminate prop sets a Checkbox to an indeterminate state, overriding its appearance and maintaining it until set to false, regardless of user interaction.

Line Through

Custom Check Icon

Controlled

Note: NextUI Checkbox also supports native events like onChange, useful for form libraries such as Formik and React Hook Form.

Slots

base: Checkbox wrapper, it handles alignment, placement, and general appearance.
wrapper: An inner container that includes styles for relative positioning, flex properties, overflow handling and managing hover and selected states.
icon: Icon within the checkbox, controlling size, visibility, and changes when checked.
label: The text associated with the checkbox.

Custom Styles

You can customize the Checkbox component by passing custom Tailwind CSS classes to the component slots.

Custom Implementation

In case you need to customize the checkbox even further, you can use the useCheckbox hook to create your own implementation.

Note: We used Tailwind Variants to implement the styles above, you can use any other library such as clsx to achieve the same result.

Data Attributes

Checkbox has the following attributes on the base element:

data-selected: When the checkbox is checked. Based on isSelected prop.
data-pressed: When the checkbox is pressed. Based on usePress
data-invalid: When the checkbox is invalid. Based on validationState prop.
data-readonly: When the checkbox is readonly. Based on isReadOnly prop.
data-indeterminate: When the checkbox is indeterminate. Based on isIndeterminate prop.
data-hover: When the checkbox is being hovered. Based on useHover
data-focus: When the checkbox is being focused. Based on useFocusRing.
data-focus-visible: When the checkbox is being focused with the keyboard. Based on useFocusRing.
data-disabled: When the checkbox is disabled. Based on isDisabled prop.
data-loading: When the checkbox is loading. Based on isLoading prop.

Accessibility

Built with a native HTML <input> element.
Full support for browser features like form autofill.
Keyboard focus management and cross browser normalization.
Keyboard event support for Tab and Space keys.
Labeling support for assistive technology.
Indeterminate state support.

API

Checkbox Props

Attribute	Type	Description	Default
children	`ReactNode`	The label of the checkbox.	-
icon	CheckboxIconProps	The icon to be displayed when the checkbox is checked.	-
value	`string`	The value of the checkbox element, used when submitting an HTML form.
name	`string`	The name of the checkbox element, used when submitting an HTML form.
size	`sm` \| `md` \| `lg`	The size of the checkbox.	`md`
color	`default` \| `primary` \| `secondary` \| `success` \| `warning` \| `danger`	The color of the checkbox.	`primary`
radius	`none` \| `sm` \| `md` \| `lg` \| `full`	The radius of the checkbox.	-
lineThrough	`boolean`	Whether the label should be crossed out.	`false`
isSelected	`boolean`	Whether the element should be selected (controlled).
defaultSelected	`boolean`	Whether the element should be selected (uncontrolled).
isRequired	`boolean`	Whether user checkbox is required on the checkbox before form submission.	`false`
isReadOnly	`boolean`	Whether the checkbox can be selected but not changed by the user.
isDisabled	`boolean`	Whether the checkbox is disabled.	`false`
isIndeterminate	`boolean`	Indeterminism is presentational only. The indeterminate visual representation remains regardless of user interaction.
isInvalid	`boolean`	Whether the checkbox is invalid.	`false`
validationState	`valid` \| `invalid`	Whether the checkbox should display its "valid" or "invalid" visual styling. (Deprecated) use isInvalid instead.	-
disableAnimation	`boolean`	Whether the animation should be disabled.	`false`
classNames	`Record<"base"｜ "wrapper"｜ "icon"｜ "label", string>`	Allows to set custom class names for the checkbox slots.	-

Checkbox Events

Attribute	Type	Description
onChange	`React.ChangeEvent<HTMLInputElement>`	Handler that is called when the element's selection state changes. You can pull out the new checked state by accessing `event.target.checked` (boolean).
onValueChange	`(isSelected: boolean) => void`	Handler that is called when the element's selection state changes.

Types

Checkbox Icon Props

type IconProps = {
  "data-checked": string;
  isSelected: boolean;
  isIndeterminate: boolean;
  disableAnimation: boolean;
  className: string;
};

type CheckboxIconProps = ReactNode | ((props: IconProps) => ReactNode);