Checkbox components

Q: How do I create a checkbox group?

There is no CheckboxGroup component in Untitled UI, and giving several checkboxes the same name only affects form submission. Wrap them in React Aria's CheckboxGroup (imported as AriaCheckboxGroup) for shared value state and a group label, or in a fieldset with a legend, and give each Checkbox a unique value.

Q: What sizes are available for checkboxes?

Set size to "sm" or "md". The default is "sm", and "md" also uses larger label and hint text.

Q: How do I show an indeterminate checkbox?

Set isIndeterminate to true, for example on a parent checkbox when only some child items are selected. It is purely visual and clicking does not clear it, so recompute it from the child selections and set it to false once all or none are selected.

Q: Can I add a label and hint text to a checkbox?

Yes. Use label for the main text and hint for supporting text below it. Both accept a ReactNode, so you can include links or formatting.

Q: How do I control checkbox state?

For a controlled checkbox, pass isSelected with an onChange handler, which receives the new boolean. For an uncontrolled one, use defaultSelected. Disable it with isDisabled.

Q: Can I use a checkbox without a visible label?

Yes. label and hint are optional, and without them only the box renders. Pass aria-label so screen readers still announce it; it goes straight through to React Aria's Checkbox.

FREE

Free and open-source React checkbox components built for modern applications and websites. These checkboxes are built using React Aria and styled with Tailwind CSS.

Checkbox example

Preview

Code

Remember me

Save my login details for next time.

Installation

You can add this checkbox component using our CLI or manually:

CLI

Manual

npx untitledui@latest add checkbox

Checkbox examples

Below are examples and variations of this checkbox component:

Base

Preview

Code

With label

Preview

Code

Remember me

With label and hint

Preview

Code

Remember me

Save my login details for next time.

Disabled

Preview

Code

Remember me

Save my login details for next time.

Sizes

Preview

Code

Remember me

Save my login details for next time.

Remember me

Save my login details for next time.

API reference

Checkbox

Import Checkbox from @/components/base/checkbox/checkbox. Renders React Aria’s Checkbox — all of its props are supported.

Checkbox props
Prop	Type	Default	Description
`size`	`"sm""md"`	`"sm"`	Controls the box size, the gap between it and the text, and the label and hint typography.
`label`	`ReactNode`	—	Content rendered beside the box. It sits inside the checkbox's label element, so it also acts as the accessible name and toggles the checkbox when clicked.
`hint`	`ReactNode`	—	Supporting text rendered under the label. Clicks on it are stopped so reading the hint does not toggle the checkbox.

Props from React Aria (42)

Checkbox inherited props
Prop	Type	Default	Description
`onClick`	`((e: MouseEvent<FocusableElement>) => void)`	—	Not recommended – use `onPress` instead. `onClick` is an alias for `onPress` provided for compatibility with other libraries. `onPress` provides additional event details for non-mouse interactions.
`onPress`	`((e: PressEvent) => void)`	—	Handler that is called when the press is released over the target.
`onPressChange`	`((isPressed: boolean) => void)`	—	Handler that is called when the press state changes.
`onPressEnd`	`((e: PressEvent) => void)`	—	Handler that is called when a press interaction ends, either over the target or when the pointer leaves the target.
`onPressStart`	`((e: PressEvent) => void)`	—	Handler that is called when a press interaction starts.
`onPressUp`	`((e: PressEvent) => void)`	—	Handler that is called when a press is released over the target, regardless of whether it started on the target or not.
`onHoverChange`	`((isHovering: boolean) => void)`	—	Handler that is called when the hover state changes.
`onHoverEnd`	`((e: HoverEvent) => void)`	—	Handler that is called when a hover interaction ends.
`onHoverStart`	`((e: HoverEvent) => void)`	—	Handler that is called when a hover interaction starts.
`onBlur`	`((e: FocusEvent<Element, Element>) => void)`	—	Handler that is called when the element loses focus.
`onFocus`	`((e: FocusEvent<Element, Element>) => void)`	—	Handler that is called when the element receives focus.
`onFocusChange`	`((isFocused: boolean) => void)`	—	Handler that is called when the element's focus status changes.
`autoFocus`	`boolean`	—	Whether the element should receive focus on render.
`excludeFromTabOrder`	`boolean`	—	Whether 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.
`onKeyDown`	`((e: KeyboardEvent) => void)`	—	Handler that is called when a key is pressed.
`onKeyUp`	`((e: KeyboardEvent) => void)`	—	Handler that is called when a key is released.
`form`	`string`	—	The `<form>` element to associate the input with. The value of this attribute must be the id of a `<form>` in the same document.
`name`	`string`	—	The name of the input element, used when submitting an HTML form.
`defaultSelected`	`boolean`	—	Whether the element should be selected (uncontrolled).
`id`	`string`	—	The element's unique identifier.
`inputRef`	`Ref<HTMLInputElement \| null>`	—	A ref for the HTML input element.
`isDisabled`	`boolean`	—	Whether the input is disabled.
`isIndeterminate`	`boolean`	—	Indeterminism is presentational only. The indeterminate visual representation remains regardless of user interaction.
`isInvalid`	`boolean`	—	Whether the input value is invalid.
`isReadOnly`	`boolean`	—	Whether the input can be selected but not changed by the user.
`isRequired`	`boolean`	—	Whether user input is required on the input before form submission.
`isSelected`	`boolean`	—	Whether the element should be selected (controlled).
`onChange`	`((isSelected: boolean) => void)`	—	Handler that is called when the element's selection state changes.
`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.
`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.
`value`	`string`	—	The value of the input element, used when submitting an HTML form.
`style`	`StyleOrFunction<CheckboxRenderProps>`	—	The inline style for the element. A function may be provided to compute the style based on component state.
`children`	`ChildrenOrFunction<CheckboxRenderProps>`	—	The children of the component. A function may be provided to alter the children based on component state.
`slot`	`string \| null`	—	A slot name for the component. Slots allow the component to receive props from a parent component. An explicit `null` value indicates that the local props completely override all props received from a parent.
`className`	`ClassNameOrFunction<CheckboxRenderProps>`	—	The CSS className for the element. A function may be provided to compute the class based on component state.
`render`	`DOMRenderFunction<"label", CheckboxRenderProps>`	—	Overrides the default DOM element with a custom render function. This allows rendering existing components with built-in styles and behaviors such as router links, animation libraries, and pre-styled components.Requirements: You must render the expected element type (e.g. if `<button>` is expected, you cannot render an `<a>`). Only a single root DOM element can be rendered (no fragments). You must pass through props and ref to the underlying DOM element, merging with your own prop as appropriate.
`aria-describedby`	`string`	—	Identifies the element (or elements) that describes the object.
`aria-details`	`string`	—	Identifies the element (or elements) that provide a detailed, extended description for the object.
`aria-label`	`string`	—	Defines a string value that labels the current element.
`aria-labelledby`	`string`	—	Identifies the element (or elements) that labels the current element.
`aria-errormessage`	`string`	—	Identifies the element that provides an error message for the object.
`aria-controls`	`string`	—	Identifies the element (or elements) whose contents or presence are controlled by the current element.

Also accepts the global HTML attributes (dir, lang, hidden, inert, translate), all standard React DOM event handlers.

CheckboxBase

Import CheckboxBase from @/components/base/checkbox/checkbox. Renders a <div> element.

CheckboxBase props
Prop	Type	Default	Description
`size`	`"sm""md"`	`"sm"`	Controls the size and corner radius of the box, and the size of the tick and dash icons inside it.
`className`	`string`	—	Additional classes merged onto the box element.
`isFocusVisible`	`boolean`	`false`	Whether to draw the keyboard focus ring around the box. Normally passed down by `Checkbox` from React Aria's render state rather than set by hand.
`isSelected`	`boolean`	—	Whether to render the checked appearance: brand-filled box with the tick faded in. Normally passed down by `Checkbox` rather than set by hand.
`isDisabled`	`boolean`	—	Whether to render the dimmed, not-allowed appearance. Normally passed down by `Checkbox` rather than set by hand.
`isIndeterminate`	`boolean`	—	Whether to render the mixed appearance: brand-filled box showing a dash, which is drawn instead of the tick even when `isSelected` is set. Normally passed down by `Checkbox` rather than set by hand.

FAQs

Please refer to our frequently asked questions page for more.

There is no CheckboxGroup component in Untitled UI, and giving several checkboxes the same name only affects form submission. Wrap them in React Aria's CheckboxGroup (imported as AriaCheckboxGroup) for shared value state and a group label, or in a fieldset with a legend, and give each Checkbox a unique value.

Set size to "sm" or "md". The default is "sm", and "md" also uses larger label and hint text.

Set isIndeterminate to true, for example on a parent checkbox when only some child items are selected. It is purely visual and clicking does not clear it, so recompute it from the child selections and set it to false once all or none are selected.

Yes. Use label for the main text and hint for supporting text below it. Both accept a ReactNode, so you can include links or formatting.

For a controlled checkbox, pass isSelected with an onChange handler, which receives the new boolean. For an uncontrolled one, use defaultSelected. Disable it with isDisabled.

Yes. label and hint are optional, and without them only the box renders. Pass aria-label so screen readers still announce it; it goes straight through to React Aria's Checkbox.

Buttons Context menus