# Checkbox Documentation Enables users to select or deselect options with support for indeterminate states. This is a documentation section that potentially contains examples, demos, and other useful information related to a specific part of Bits UI. When helping users with this documentation, you can ignore the classnames applied to the demos unless they are relevant to the user's issue. Copy Page ```svelte

{#snippet children({ checked, indeterminate })}

{#if indeterminate} {:else if checked} {/if}

{/snippet} Accept terms and conditions

``` ## Overview The Checkbox component provides a flexible and accessible way to create checkbox inputs in your Svelte applications. It supports three states: checked, unchecked, and indeterminate, allowing for complex form interactions and data representations. ## Key Features - **Tri-State Support**: Handles checked, unchecked, and indeterminate states, providing versatility in form design. - **Accessibility**: Built with WAI-ARIA guidelines in mind, ensuring keyboard navigation and screen reader support. - **Flexible State Management**: Supports both controlled and uncontrolled state, allowing for full control over the checkbox's checked state. ## Architecture The Checkbox component is composed of the following parts: - **Root**: The main component that manages the state and behavior of the checkbox. ## Structure Here's an overview of how the Checkbox component is structured in code: ```svelte {#snippet children({ checked, indeterminate })} {#if indeterminate} - {:else if checked} ✅ {:else} ❌ {/if} {/snippet} ``` ## Reusable Components It's recommended to use the `Checkbox` primitive to create your own custom checkbox component that can be used throughout your application. In the example below, we're using the `Checkbox` and [`Label`](/docs/components/label) components to create a custom checkbox component. MyCheckbox.svelte ```svelte {#snippet children({ checked, indeterminate })} {#if indeterminate} - {:else if checked} ✅ {:else} ❌ {/if} {/snippet} {labelText} ``` You can then use the `MyCheckbox` component in your application like so: +page.svelte ```svelte ``` ## Managing Checked State This section covers how to manage the `checked` state of the Checkbox. ### Two-Way Binding Use `bind:checked` for simple, automatic state synchronization: ```svelte ``` ### Fully Controlled Use a [Function Binding](https://svelte.dev/docs/svelte/bind#Function-bindings) for complete control over the state's reads and writes. ```svelte ``` ## Managing Indeterminate State This section covers how to manage the `indeterminate` state of the Checkbox. ### Two-Way Binding Use `bind:indeterminate` for simple, automatic state synchronization: ```svelte ``` ### Fully Controlled Use a [Function Binding](https://svelte.dev/docs/svelte/bind#Function-bindings) for complete control over the state's reads and writes. ```svelte ``` ## Disabled State You can disable the checkbox by setting the `disabled` prop to `true`. ```svelte ``` ## HTML Forms If you set the `name` prop, a hidden checkbox input will be rendered to submit the value of the checkbox with a form. By default, the checkbox will be submitted with default checkbox value of `'on'` if the `checked` prop is `true`. ```svelte ``` ### Custom Input Value If you'd prefer to submit a different value, you can use the `value` prop to set the value of the hidden input. For example, if you wanted to submit a string value, you could do the following: ```svelte ``` ### Required If you want to make the checkbox required, you can use the `required` prop. ```svelte ``` This will apply the `required` attribute to the hidden input element, ensuring that proper form submission is enforced. ## Checkbox Groups You can use the `Checkbox.Group` component to create a checkbox group. ```svelte Notifications ``` Expand Code ```svelte Notifications

{@render MyCheckbox({ label: "Marketing", value: "marketing" })} {@render MyCheckbox({ label: "Promotions", value: "promotions" })} {@render MyCheckbox({ label: "News", value: "news" })} {@render MyCheckbox({ label: "Updates", value: "updates" })}

{#snippet MyCheckbox({ value, label }: { value: string; label: string })} {@const id = useId()}

{#snippet children({ checked, indeterminate })}

{#if indeterminate} {:else if checked} {/if}

{/snippet} {label}

{/snippet} ``` ### Managing Value State This section covers how to manage the `value` state of a Checkbox Group. #### Two-Way Binding Use `bind:value` for simple, automatic state synchronization: ```svelte Items ``` #### Fully Controlled Use a [Function Binding](https://svelte.dev/docs/svelte/bind#Function-bindings) for complete control over the state's reads and writes. ```svelte ``` ### HTML Forms To render hidden `` elements for the various checkboxes within a group, pass a `name` to `Checkbox.Group`. All descendent checkboxes will then render hidden inputs with the same name. ```svelte ``` When a `Checkbox.Group` component is used, its descendent `Checkbox.Root` components will use certain properties from the group, such as the `name`, `required`, and `disabled`. ## API Reference ### Checkbox.Root The button component used to toggle the state of the checkbox. | Property | Type | Description | Details | | ------------------------- | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | | `checked` $bindable | `boolean` | The checkbox button's checked state.`Default: false` | | | `onCheckedChange` | `function` - (checked: boolean) => void | A callback that is fired when the checkbox button's checked state changes.`Default: —— undefined` | | | `indeterminate` $bindable | `boolean` | Whether the checkbox is an indeterminate state or not.`Default: false` | | | `onIndeterminateChange` | `function` - (indeterminate: boolean) => void | A callback that is fired when the indeterminate state changes.`Default: —— undefined` | | | `disabled` | `boolean` | Whether or not the checkbox button is disabled. This prevents the user from interacting with it.`Default: false` | | | `required` | `boolean` | Whether or not the checkbox is required.`Default: false` | | | `name` | `string` | The name of the checkbox. If provided a hidden input will be render to use for form submission. If not provided, the hidden input will not be rendered.`Default: —— undefined` | | | `value` | `string` | The value of the checkbox. This is what is submitted with the form when the checkbox is checked.`Default: —— undefined` | | | `readonly` | `boolean` | Whether or not the checkbox is read only. If `true`, the checkbox will be focusable by the user, but will not be able to be checked/unchecked.`Default: false` | | | `ref` $bindable | `HTMLButtonElement` | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default: null` | | | `children` | `Snippet` - type ChildrenSnippetProps = { checked: boolean; indeterminate: boolean; }; | The children content to render.`Default: —— undefined` | | | `child` | `Snippet` - type ChildSnippetProps = { props: Record\; checked: boolean; indeterminate: boolean; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default: —— undefined` | | | Data Attribute | Value | Description | Details | | -------------------- | ---------------------------------------------------- | ------------------------------------------------------------- | ------- | | `data-state` | `enum` - 'checked' \| 'unchecked' \| 'indeterminate' | The checkbox's state of checked, unchecked, or indeterminate. | | | `data-disabled` | `''` | Present when the checkbox is disabled. | | | `data-readonly` | `''` | Present when the checkbox is read only. | | | `data-checkbox-root` | `''` | Present on the root element. | | ### Checkbox.Group A group that synchronizes its value state with its descendant checkboxes. | Property | Type | Description | Details | | ----------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- | | `value` $bindable | `string[]` | The value of the group. This is an array of the values of the checked checkboxes within the group.`Default: []` | | | `onValueChange` | `function` - (value: string\[]) => void | A callback that is fired when the checkbox group's value state changes.`Default: —— undefined` | | | `disabled` | `boolean` | Whether or not the checkbox group is disabled. If `true`, all checkboxes within the group will be disabled. To disable a specific checkbox in the group, pass the `disabled` prop to the checkbox.`Default: false` | | | `required` | `boolean` | Whether or not the checkbox group is required for form submission.`Default: false` | | | `name` | `string` | The name of the checkbox group. If provided a hidden input will be rendered to use for form submission.`Default: —— undefined` | | | `readonly` | `boolean` | Whether or not the checkbox group is read only. If `true`, the group will be focusable by the user, but the checkboxes will not be able to be checked/unchecked.`Default: false` | | | `ref` $bindable | `HTMLDivElement` | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default: null` | | | `children` | `Snippet` | The children content to render.`Default: —— undefined` | | | `child` | `Snippet` - type SnippetProps = { props: Record\; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default: —— undefined` | | | Data Attribute | Value | Description | Details | | --------------------- | ----- | --------------------------------------------- | ------- | | `data-disabled` | `''` | Present when the checkbox group is disabled. | | | `data-checkbox-group` | `''` | Present on the group element. | | | `data-readonly` | `''` | Present when the checkbox group is read only. | | ### Checkbox.GroupLabel An accessible label for the checkbox group. | Property | Type | Description | Details | | --------------- | --------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ------- | | `ref` $bindable | `HTMLLabelElement` | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default: null` | | | `children` | `Snippet` | The children content to render.`Default: —— undefined` | | | `child` | `Snippet` - type SnippetProps = { props: Record\; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default: —— undefined` | | | Data Attribute | Value | Description | Details | | --------------------------- | ----- | -------------------------------------------- | ------- | | `data-disabled` | `''` | Present when the checkbox group is disabled. | | | `data-checkbox-group-label` | `''` | Present on the label element. | | [Previous Calendar](/docs/components/calendar) [Next Collapsible](/docs/components/collapsible)