# Checkbox A checkbox with a third, indeterminate state, for a choice a form submits. Checkbox is a tri-state checkbox that takes part in forms. Useful wherever a choice should only count once the form is submitted; for a setting that applies immediately, use [`Switch`](/components/switch). ::component-preview{name="CheckboxPreview"} ```vue ``` :: ## Usage guidelines - Make sure the checkbox has an accessible name, either through a [`Label`](/components/label) inside a [`Field`](/components/field) or an `aria-label` on the root. - Bind the mixed state with `v-model:indeterminate`. Passed as a plain prop it is controlled, so activating the checkbox emits but leaves the mixed state on screen. - `options.readOnly` never reaches the hidden input, so a read-only checkbox still submits its value. Use `options.disabled` to leave it out of the submission. ## Anatomy Assemble the root and its indicator. ::component-anatomy --- parts: - name: Checkbox.Root required: true description: Renders a button with role="checkbox", plus a visually hidden checkbox input. children: - name: Checkbox.Indicator description: Renders a span. Unmounted while unchecked. --- :: ```vue ``` ## Examples ### Controlled and uncontrolled Leave `modelValue` out and the checkbox keeps its own state, seeded by `defaultValue`. Bind `v-model` and you own it instead, which is [decided once at mount](/components/composition#controlled-and-uncontrolled). ```vue ``` ### Indeterminate `indeterminate` is independent of the checked state, so the two are reported separately in `data-state`, `data-checked` and `data-indeterminate`. ```vue ``` Activating an indeterminate checkbox sets it checked and clears indeterminate, the way a native tri-state input behaves. ### Driving a list of children Work both flags out from the children, and write back when either changes. ```vue ``` ### Inside a form The hidden input takes `name`, `value`, `required` and `disabled`, so [the form sees it](/components/form-integration#form-participation), and a surrounding `Field` supplies each of them. ```vue ``` An unchecked checkbox submits nothing, which is the native behaviour. If you need a value either way, set `uncheckedValue` and a second hidden input holds it while the checkbox is unchecked. ```vue ``` A checkbox rendered outside the `
` it belongs to, in a dialog or a sticky footer, points at it by `id` through `form`. Both hidden inputs take the attribute. ```vue ``` ### Reaching the hidden input The element the form actually submits is exposed as `input` on the component instance, for the rare case that wants to read `validity` or call `setCustomValidity()` on it. ```vue ``` ### Styling from state Paint the root from `data-state`, and read the same values as slot props where the markup itself has to branch. ```vue ``` The indicator is unmounted while the checkbox is unchecked. If you would rather animate it yourself, `options.forceMount` keeps it in the DOM in every state. ```vue ``` ## API reference **Module.** A bundled `options` object, and `useMirrorCheckbox(id)` as the programmatic API. ### `Checkbox.Root` Renders a `