# Checkbox (/components/forms/checkbox)
Use `Checkbox` when someone can choose an option independently of nearby controls. Pass
`description` to clarify what the option means.
apps/docs/src/examples/checkbox/basic.tsx
```tsx
import { Checkbox } from '@luke-ui/react/checkbox';
export default () => {
return Email notifications;
};
```
## States [#states]
Use `defaultSelected` for an uncontrolled initial value, or pair `isSelected` with `onChange` when
application state owns the selection. `isIndeterminate` communicates a mixed state, such as a parent
option whose child options are only partly selected.
apps/docs/src/examples/checkbox/states.tsx
```tsx
import { Checkbox } from '@luke-ui/react/checkbox';
import { Comparison, ComparisonItem } from '#docs/comparison';
export default () => {
return (
Example checkbox
Example checkbox
Example checkbox
Example checkbox
Example checkbox
Example checkbox
Example checkbox
);
};
```
apps/docs/src/examples/checkbox/controlled.tsx
```tsx
import { Checkbox } from '@luke-ui/react/checkbox';
import { useState } from 'react';
export default () => {
const [isSelected, setIsSelected] = useState(false);
return (
{isSelected ? 'Checked' : 'Unchecked'}
);
};
```
## Size [#size]
Use `size` to change the checkbox control. It does not change the label typography. `medium` is the
default. Use `small` in compact layouts and `large` where a larger control improves scanning.
apps/docs/src/examples/checkbox/sizes.tsx
```tsx
import { Checkbox } from '@luke-ui/react/checkbox';
import { Comparison, ComparisonItem } from '#docs/comparison';
export default () => {
return (
Example checkbox
Example checkbox
Example checkbox
);
};
```
## Validation [#validation]
Set `isRequired` to require the choice. `Checkbox` shows its validation message after validation
fails. Pass `errorMessage` only for an error you already have, such as one from a form library or
your server. A non-empty message marks the checkbox invalid. Read [Validation](/docs/validation) for
where messages come from and how to write them.
apps/docs/src/examples/checkbox/validation.tsx
```tsx
import { Box } from '@luke-ui/react/box';
import { Button } from '@luke-ui/react/button';
import { Checkbox } from '@luke-ui/react/checkbox';
import type { SubmitEvent } from 'react';
export default () => {
function handleSubmit(event: SubmitEvent) {
event.preventDefault();
}
return (
);
};
```
## Labels with Text [#labels-with-text]
Wrap a checkbox in block `Text` when its label needs a specific text size. The control follows the
inherited line height. It keeps its fixed visual square centred on the first line when the label
wraps. Outside `Text`, it uses the normal compact control size.
apps/docs/src/examples/checkbox/first-line-alignment.tsx
```tsx
import { Box } from '@luke-ui/react/box';
import { Checkbox } from '@luke-ui/react/checkbox';
import { Text } from '@luke-ui/react/text';
export default () => {
return (
A longer label keeps its control aligned when it wraps.
Larger text keeps the same first-line alignment when it wraps.
);
};
```
## Accessibility [#accessibility]
Pass a visible label as `Checkbox` children. Use `aria-label` only when surrounding content already
names the control.
Disabled checkboxes cannot receive focus, and their value cannot change. Read-only checkboxes remain
focusable, so someone who uses a keyboard or assistive technology can still perceive their state.
Keyboard navigation shows a focus ring. Pointer focus does not.
## Related components [#related-components]
Use the [Checkbox primitive](/components/primitives/checkbox) to arrange the clickable content,
control, indicator, description, and error slots yourself.
## API [#api]