Checkbox

Checkboxes allow users to select multiple items from a list of individual items, or to mark one individual item as selected. Checkbox implementation is based on @react-aria/checkbox

import { Checkbox } from '@nextui-org/react';

Default

Checkboxes accept children, which are rendered as the label.

Disabled

Unusable and un-clickable Checkbox.

Sizes

Change the size of the entire Checkbox including padding, font-size and border with the size property.

Colors

You can change the color with color prop

Label Colors

You can change the Checkbox text color with labelColor prop

Rounded

You can change the full style to a rounded Checkbox with the isRounded property.

Indeterminate

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

Line Through

Add a line in the middle of the label when the Checkbox is checked with the property lineThrough

Controlled vs Uncontrolled

Checkboxes are not selected by default. The defaultSelected prop can be used to set the default state (uncontrolled). Alternatively, the isSelected prop can be used to make the selected state controlled.

Note: See React's documentation on uncontrolled components for more info.

Disable animation

You can disable the animation of the entire Checkbox with the property disableAnimation.

APIs

Checkbox Props

AttributeTypeDescriptionDefault
childrenReactNodeThe label for the element-
valuestringThe value of the input element, used when submitting an HTML form. See MDN-
labelstringThe label for the element-
namestringThe name of the input element, used when submitting an HTML form. See MDN-
colorNormalColorsThe color of the componentdefault
labelColorSimpleColorsThe color of the labeldefault
sizeNormalSizesThe size of the componentmd
isSelectedbooleanWhether the element should be selected (controlled)false
defaultSelectedbooleanWhether the element should be selected (uncontrolled)false
disableAnimationbooleanWhether the checkbox has animationsfalse
isDisabledbooleanWhether the input is disabledfalse
isIndeterminatebooleanIndeterminism is presentational only. The indeterminate visual representation remains regardless of user interaction.false
isRoundedbooleanWhether the checkbox is roundedfalse
lineThroughbooleanLine in the middle of the label when the Checkbox is checked-
isReadOnlybooleanWhether the input can be selected but not changed by the user.false
isRequiredbooleanWhether user input is required on the input before form submission.false
autoFocusbooleanWhether the element should receive focus on render
cssStitches.CSSOverride Default CSS style-
askeyof JSX.IntrinsicElementsChanges which tag component outputslabel

Checkbox Events

AttributeTypeDescriptionDefault
onChange(checked: boolean) => voidHandler that is called when the element's selection state changes-
onFocus(e: FocusEvent) => voidHandler that is called when the element receives focus-
onBlur(e: FocusEvent) => voidHandler that is called when the element loses focus-
onFocusChange(focused: 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-

Checkbox Accessibility Props

AttributeTypeDescriptionDefault
idstringThe element's unique identifier. See MDN-
excludeFromTabOrderbooleanWhether to exclude the element from the sequential tab order. If true, the element will not be focusable via the keyboard by tabbing. This should be avoided except in rare scenarios where an alternative means of accessing the element or its functionality via the keyboard is available.-
aria-controlsstringIdentifies the element (or elements) whose contents or presence are controlled by the current element.-
aria-labelstringDefines a string value that labels the current element-
aria-labelledbystringIdentifies the element (or elements) that labels the current element-
aria-describedbystringIdentifies the element (or elements) that describes the object.-
aria-detailsstringIdentifies the element (or elements) that provide a detailed, extended description for the object.-
aria-errormessagestringIdentifies the element that provides an error message for the object.-

Checkbox types

Normal Colors

type NormalColors =
  | 'default'
  | 'primary'
  | 'secondary'
  | 'success'
  | 'warning'
  | 'error'
  | 'gradient';

Simple Colors

type SimpleColors =
  | 'default'
  | 'primary'
  | 'secondary'
  | 'success'
  | 'warning'
  | 'error';

Normal Sizes

type NormalSizes = 'xs' | 'sm' | 'md' | 'lg' | 'xl';

Keyboard event

type BaseEvent<ReactKeyboardEvent<any>>
gradient blue backgroundgradient violet background