# Checkbox Field (/components/forms/checkbox-field)
Use `CheckboxField` when someone can choose an option independently of nearby controls. Pass `label`
to name the option, and `description` to clarify what it means.
Use [`CheckboxGroup`](/components/forms/checkbox-group) when related options need a shared label and
validation message.
apps/docs/src/examples/checkbox-field/basic.tsx
```tsx
import { CheckboxField } from '@luke-ui/react/checkbox-field';
export default () => {
return `, so pass
textual content only. Place links and buttons next to the checkbox. Inline typography such as
`Strong` works inside the label. Set `slot={null}` on a `Text` you place there, as the
[Checkbox primitive](/components/primitives/checkbox#text-in-the-label) describes.
When another part of the layout draws the visible label, such as a table row or a settings row,
compose the [Checkbox primitive](/components/primitives/checkbox) and name the control with
`aria-labelledby`.
## 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-field/states.tsx
```tsx
import { CheckboxField } from '@luke-ui/react/checkbox-field';
import { Comparison, ComparisonItem } from '#docs';
export default () => {
return (
);
};
```
apps/docs/src/examples/checkbox-field/controlled.tsx
```tsx
import { CheckboxField } from '@luke-ui/react/checkbox-field';
import { useState } from 'react';
export default () => {
const [isSelected, setIsSelected] = useState(false);
return (
);
};
```
## Validation [#validation]
Set `isRequired` to require the choice. `CheckboxField` 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.
Inside a [`CheckboxGroup`](/components/forms/checkbox-group#validation), set `isRequired` or pass
`validate` on the child for native validation. Pass controlled or server errors to the group's
`errorMessage`.
apps/docs/src/examples/checkbox-field/validation.tsx
```tsx
import { Button } from '@luke-ui/react/button';
import { CheckboxField } from '@luke-ui/react/checkbox-field';
import { Cluster } from '@luke-ui/react/cluster';
import { Stack } from '@luke-ui/react/stack';
import type { SubmitEvent } from 'react';
function handleSubmit(event: SubmitEvent) {
event.preventDefault();
}
export default () => {
return (
);
};
```
## Required marker [#required-marker]
By default, a required checkbox shows a marker after its `label`. Read
[Required fields](/docs/forms#required-fields) for the `necessityIndicator` values.
## 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-field/first-line-alignment.tsx
```tsx
import { CheckboxField } from '@luke-ui/react/checkbox-field';
import { Stack } from '@luke-ui/react/stack';
import { Text } from '@luke-ui/react/text';
export default () => {
return (
);
};
```
## IDs and refs [#ids-and-refs]
`id`, `className`, and `ref` target the root element. `inputId` and `inputRef` target the input.
## Form values [#form-values]
Pass `name` so the checkbox joins `FormData` when selected. Pass `value` to set the submitted value,
and `form` to associate a checkbox with a `