--- package: "@svenskaspel/ui" version: "4.4.0" document_type: "component-documentation" source: "@svenskaspel/ui/docs/checkbox.md" canonical_url: "/components/checkbox" usage_source: "src/app/(docs)/components/checkbox/page.mdx" --- # Checkbox Checkbox allows users to select one or more items from a set, turning options on or off. ![Checkbox](/images/components/checkbox/checkbox-figma-13632.webp) *** ## Usage Checkboxes allow the user to enable or disable options in a form setting. Multiple checkboxes may be presented in group, where the user can enable none, one or several options. For a longer list of options consider using the select component. Typically an associated action is required for settings changed to be confirmed. For scenarios where only one option may be enabled at one time, use a radio group. For designs outside of a form setting, where the enabling or disabling is expected to be triggered immediately consider using a switch. ### Text labels Provide a label text to clearly indicate what option the associated checkbox enables or disables. Avoid too long label texts, the content should not exceed one line. Use the description field if extra clarification is required. ![Text labels – 1](/images/components/checkbox/checkbox-figma-1f6fc.webp) > **Do:** Provide a clear concise label for each checkbox ![Text labels – 2](/images/components/checkbox/checkbox-figma-e73e4.webp) > **Don't:** Don’t be unclear or unnecessarily wordy to describe what the setting means. *** ## Formatting ### Anatomy The checkbox features a label, along with an optional description text. ![Anatomy](/images/components/checkbox/checkbox-figma-61d39.webp) 1. Checkbox 2. Label 3. Description *** ## Behaviour ### States The checkbox allows for a set of states: selected, unselected and indeterminate. Indeterminate indicates that a subgroup of checkboxes have a mix of selected and unselected states. ![States](/images/components/checkbox/checkbox-figma-cd309.webp) 1. Selected 2. Unselected 3. Indeterminate *** ## Modify ### Alignment The checkbox can be aligned to the left or the right within a design, according to needs. ![Alignment](/images/components/checkbox/checkbox-figma-5be1f.webp) Left- and right aligned checkboxes. ### Description field If further explanation is required in order to communicate what the associated option means, further clarification can be added in the description text. ![Description field](/images/components/checkbox/checkbox-figma-e6f0e.webp) A checkbox with label and description text. --- # Readme / API # `Checkbox` The `Checkbox` component is a reusable checkbox component built on top of the Base UI `Checkbox` primitive. ## Importing ```typescript import { Checkbox } from '@svenskaspel/ui/react/checkbox'; ``` ## Props Accepts Base UI `Checkbox.Root` props except `render`. Common props: | Prop | Type | Description | | ----------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------ | | `checked` | `boolean` | Controls the checked state of the checkbox. | | `defaultChecked` | `boolean` | Sets the default checked state for an uncontrolled component. | | `indeterminate` | `boolean` | Renders the checkbox in a mixed state. Independent of `checked` — set to `false` when the user ticks the checkbox. | | `onCheckedChange` | `(checked: boolean) => void` | Callback invoked when the checked state changes. Always receives a boolean. | | `disabled` | `boolean` | Disables the checkbox when set to `true`. | | `readOnly` | `boolean` | Prevents user interaction while keeping the checkbox focusable. | | `required` | `boolean` | Marks the checkbox as required in a form. | | `name` | `string` | The name of the checkbox input, used for form submission. | | `value` | `string` | The value submitted when the checkbox is checked. Defaults to the native `'on'`. | | `id` | `string` | Adds an `id` to the checkbox element, useful for accessibility and labels. | ## Usage Here is a basic example of how to use the `Checkbox` component: ```typescript import * as React from 'react'; import { Checkbox } from '@svenskaspel/ui/react/checkbox'; const MyComponent = () => { return ; }; export default MyComponent; ``` Here is an example of how to control the state of the `Checkbox` component: ```typescript import * as React from 'react'; import { Checkbox } from '@svenskaspel/ui/react/checkbox'; const MyComponent = () => { const [checked, setChecked] = React.useState(false); return ; }; export default MyComponent; ``` ### Indeterminate state The mixed / indeterminate state is a separate boolean prop. Toggle it independently of `checked`: ```typescript import * as React from 'react'; import { Checkbox } from '@svenskaspel/ui/react/checkbox'; const MyComponent = () => { const [checked, setChecked] = React.useState(false); const [indeterminate, setIndeterminate] = React.useState(true); return ( { setIndeterminate(false); setChecked(next); }} /> ); }; ``` ## Server-side Form Integration The `Checkbox` component supports native HTML form integration. When you provide a `name` prop, the underlying Base UI primitive renders a hidden native `` beside the visible checkbox that participates in form submission. **Basic form usage** ```typescript import { Checkbox } from '@svenskaspel/ui/react/checkbox'; import { Label } from '@svenskaspel/ui/react/label'; function FormExample() { const handleSubmit = (event: React.FormEvent) => { event.preventDefault(); const formData = new FormData(event.currentTarget); const termsAccepted = formData.get('terms'); // 'on' when checked, null when unchecked console.log('Terms accepted:', termsAccepted); }; return (
); } ``` **Custom value** Provide a custom value that will be submitted instead of the default `'on'`: ```typescript ``` **Multiple checkboxes with the same name** Multiple checkboxes can share the same `name` to submit an array of values: ```typescript function MultiSelectForm() { const handleSubmit = (event: React.FormEvent) => { event.preventDefault(); const formData = new FormData(event.currentTarget); const sports = formData.getAll('sports'); // ['soccer', 'tennis'] if both checked console.log('Selected sports:', sports); }; return (
); } ``` ## Styling The `Checkbox` component uses the utility function `cn` from `"@svenskaspel/ui/utils"` to concatenate default styles with any additional `className` passed as a prop. The primitive exposes `data-checked`, `data-unchecked`, `data-indeterminate`, and `data-disabled` attributes for state-based styling.