> ## Documentation Index
> Fetch the complete documentation index at: https://docs.twenty.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Checkbox
> Select independent options with checked and indeterminate states.
export const StoryEmbed = ({storyId, title, height = 120}) => <>
Open in Storybook
;
Use `Checkbox` when each option can be selected independently. For a mutually exclusive choice, use [RadioGroup](/ui/primitives/input/radio-group).
## Usage
### Uncontrolled state
Use `defaultChecked` to set the initial checked state. The checkbox owns subsequent changes.
```tsx theme={null}
import { useId } from 'react';
import { Checkbox } from 'twenty-ui/primitives/input';
import { Text } from 'twenty-ui/primitives/typography';
export const EmailPreference = () => {
const checkboxId = useId();
return (
);
};
```
A checked, named checkbox contributes its value to a form. Set `uncheckedValue` if the form should also submit a value when it is unchecked.
## Appearance and interaction
Compare checked, indeterminate, and disabled states, then choose the color, size, shape, and variant independently. The enabled examples can be toggled.
| Prop | Values | Default |
| - | - | - |
| `size` | `sm`, `md` | `sm` |
| `variant` | `solid`, `outline`, `soft` | `solid` |
| `shape` | `square`, `round` | `square` |
| `color` | `accent`, `success`, `warning` | `accent` |
Tab focuses the checkbox and Space toggles it. Clicking its label also toggles it. Use `disabled` to prevent interaction, or `readOnly` when the value should remain unchanged while the control stays focusable. Keep meaning in the label rather than communicating it through color alone.
## Controlled state
Pass `checked` and update it with `onCheckedChange` to own the same preference in React state. The callback receives the next boolean and event details.
```tsx theme={null}
import { useId, useState } from 'react';
import { Checkbox } from 'twenty-ui/primitives/input';
import { Text } from 'twenty-ui/primitives/typography';
export const EmailPreference = () => {
const checkboxId = useId();
const [checked, setChecked] = useState(true);
return (
);
};
```
## Indeterminate state
An indeterminate checkbox represents a partial selection. Derive it from the child options independently of the checkbox's checked state.
```tsx theme={null}
import { useState } from 'react';
import { Checkbox } from 'twenty-ui/primitives/input';
export const ColumnSelection = () => {
const [showEmail, setShowEmail] = useState(true);
const [showPhone, setShowPhone] = useState(false);
return (
);
};
```
## Parts and custom content
`Checkbox` assembles the styled root and its default check and indeterminate icons. Use `Checkbox.Root` with `Checkbox.Indicator` to own the indicator content. Root owns state and box appearance; Indicator renders the content you supply.
```tsx theme={null}
import { IconCheck } from 'twenty-ui/icon';
import { Checkbox } from 'twenty-ui/primitives/input';
export const CustomPreference = () => (
);
```
`CheckboxRootProps` and `CheckboxIndicatorProps` are public types exported from `twenty-ui/primitives/input`. Both parts accept native attributes, handlers, refs, `render`, and state-based `className` and `style` callbacks. Root's `ref` targets the visible control; `inputRef` targets the native input. The part ref targets its rendered element. Pass `nativeButton` with `render={}` when replacing Root with a button. Appearance props belong on Root; explicit classes and styles are merged with the defaults.
Indicator receives checked and indeterminate state, including transition state. Set `keepMounted` to retain an unchecked indicator in the DOM; the default styling hides it with opacity. Override its `style` or `className` for custom transitions.
The callable assembly and its `CheckboxProps` type remain supported. Replace the assembly with Root and its part when supplying custom icons instead of appending another part to the assembly's children.
For controlled form reset, handle the form's `onReset` and restore `checked` to your initial value. Base UI 1.8 does not restore uncontrolled component state on native form reset. `required`, `form`, `value`, and `uncheckedValue` keep the upstream native input behavior.
## Props
The reference is generated from the public component types. Native attributes, including accessible names and event handlers, are also accepted on parts that render elements.
Whether the checkbox is currently ticked.
To render an uncontrolled checkbox, use the `defaultChecked` prop instead.
CSS class applied to the element, or a function that
returns a class based on the component's state.
Color used while the checkbox is checked or indeterminate.
Whether the checkbox is initially ticked.
To render a controlled checkbox, use the `checked` prop instead.
Whether the component should ignore user interaction.
Identifies the form that owns the hidden input.
Useful when the checkbox is rendered outside the form.
Adds padding and a hover background around the box.
The id of the input element.
Whether the checkbox is in a mixed state: neither ticked, nor unticked.
A ref to access the hidden `` element.
Identifies the field when a form is submitted.
Whether the component renders a native `
Event handler called when the checkbox is ticked or unticked.
Whether the checkbox controls a group of child checkboxes.
Must be used in a [Checkbox Group](https://base-ui.com/react/components/checkbox-group).
Whether the user should be unable to tick or untick the checkbox.
Allows you to replace the component's HTML element
with a different tag, or compose it with another component.
Accepts a `ReactElement` or a function that returns the element to render.
Whether the user must tick the checkbox before submitting a form.
Corner shape of the box.
Visual size of the checkbox.
Style applied to the element, or a function that
returns a style object based on the component's state.
The value submitted with the form when the checkbox is unchecked.
By default, unchecked checkboxes do not submit any value, matching native checkbox behavior.
The checkbox's value. Identifies it within a [Checkbox Group](https://base-ui.com/react/components/checkbox-group), falling back to `name` when omitted.
When submitting a form, a checked box submits `value`; with no `value`, it submits the native "on".
Visual style of the box: filled, outlined, or tinted.
### Checkbox.Root
Whether the checkbox is currently ticked.
To render an uncontrolled checkbox, use the `defaultChecked` prop instead.
CSS class applied to the element, or a function that
returns a class based on the component's state.
Color used while the checkbox is checked or indeterminate.
Whether the checkbox is initially ticked.
To render a controlled checkbox, use the `checked` prop instead.
Whether the component should ignore user interaction.
Identifies the form that owns the hidden input.
Useful when the checkbox is rendered outside the form.
Adds padding and a hover background around the box.
The id of the input element.
Whether the checkbox is in a mixed state: neither ticked, nor unticked.
A ref to access the hidden `` element.
Identifies the field when a form is submitted.
Whether the component renders a native `
Event handler called when the checkbox is ticked or unticked.
Whether the checkbox controls a group of child checkboxes.
Must be used in a [Checkbox Group](https://base-ui.com/react/components/checkbox-group).
Whether the user should be unable to tick or untick the checkbox.
Allows you to replace the component's HTML element
with a different tag, or compose it with another component.
Accepts a `ReactElement` or a function that returns the element to render.
Whether the user must tick the checkbox before submitting a form.
Corner shape of the box.
Visual size of the checkbox.
Style applied to the element, or a function that
returns a style object based on the component's state.
The value submitted with the form when the checkbox is unchecked.
By default, unchecked checkboxes do not submit any value, matching native checkbox behavior.
The checkbox's value. Identifies it within a [Checkbox Group](https://base-ui.com/react/components/checkbox-group), falling back to `name` when omitted.
When submitting a form, a checked box submits `value`; with no `value`, it submits the native "on".
Visual style of the box: filled, outlined, or tinted.
### Checkbox.Indicator
CSS class applied to the element, or a function that
returns a class based on the component's state.
Whether to keep the element in the DOM when the checkbox is not checked.
Allows you to replace the component's HTML element
with a different tag, or compose it with another component.
Accepts a `ReactElement` or a function that returns the element to render.
Style applied to the element, or a function that
returns a style object based on the component's state.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.