Checkbox
Checkboxes allow users to toggle an option on or off.
Checkboxes are interactive form controls that let users select one or more options by toggling them on or off. They are commonly used in forms, filter panels, and preference settings.
The
Checkbox component provides accessible markup, design tokens for customization, and states for checked, disabled, and partial (partially checked).Example
Code
Usage
Import the component
_10import { Checkbox } from '@faststore/ui'
Import styles
To apply styles, include the following in your stylesheet:
_10@import '@faststore/ui/src/components/atoms/Checkbox/styles.scss';
For details, see Importing FastStore UI component styles.
Examples
Checked
Example
Code
Disabled
Example
Code
Partial
Example
Code
Design tokens
| Local token | Default value/Global token linked |
|---|---|
--fs-checkbox-width | 1.25rem |
--fs-checkbox-height | var(--fs-checkbox-width) |
--fs-checkbox-border-width | var(--fs-border-width) |
--fs-checkbox-border-radius | var(--fs-border-radius) |
--fs-checkbox-border-color | var(--fs-border-color) |
--fs-checkbox-border-color-hover | var(--fs-border-color-active) |
--fs-checkbox-transition | border var(--fs-transition-timing) var(--fs-transition-function), background-color var(--fs-transition-timing) var(--fs-transition-function), box-shadow var(--fs-transition-timing) var(--fs-transition-function) |
--fs-checkbox-bkg-color-hover | var(--fs-color-primary-bkg-light) |
--fs-checkbox-shadow-hover | 0 0 0 var(--fs-checkbox-border-width) var(--fs-border-color-active) |
Design tokens: Checked
Checked checkboxes use a filled primary background and focused hover accents to clearly indicate selection while maintaining accessible contrast and feedback.
| Local token | Default value/Global token linked |
|---|---|
--fs-checkbox-checked-bkg-color | var(--fs-color-primary-bkg) |
--fs-checkbox-checked-bkg-color-hover | var(--fs-color-primary-bkg-hover) |
--fs-checkbox-checked-border-color-hover | var(--fs-border-color-hover) |
--fs-checkbox-checked-shadow-hover | 0 0 0 var(--fs-checkbox-border-width)
var(--fs-checkbox-checked-border-color-hover) |
Design tokens: Disabled
Disabled checkboxes lower contrast and remove interactive feedback, preserving layout without suggesting availability.
| Local token | Default value/Global token linked |
|---|---|
--fs-checkbox-disabled-bkg-color | var(--fs-color-disabled-bkg) |
--fs-checkbox-disabled-border-width | var(--fs-checkbox-border-width) |
--fs-checkbox-disabled-border-color | var(--fs-border-color-disabled) |
--fs-checkbox-disabled-text-color | var(--fs-color-disabled-text) |
Design tokens: Partial
Partial checkboxes present a neutral surface with a primary accent to convey a mixed selection state, useful for parent options of grouped items.
| Local token | Default value/Global token linked |
|---|---|
--fs-checkbox-partial-bkg-color | var(--fs-color-body-bkg) |
--fs-checkbox-partial-border-width | var(--fs-checkbox-border-width) |
--fs-checkbox-partial-border-color | var(--fs-color-primary-bkg) |
--fs-checkbox-partial-bkg-color-hover | var(--fs-color-primary-bkg-light) |
Data attributes
You can target and override
Checkbox styles using the following data attributes:data-fs-checkboxProps
| Name | Type | Description | Default |
|---|---|---|---|
| testId | string | ID to find this component in testing tools (e.g.: cypress, testing library, and jest). | fs-checkbox |
| partial | false | true | Boolean that represents a partial state. |
Best practices
✅ Do's
- Always pair a Checkbox with a descriptive Label to improve accessibility and clarify the option’s purpose.
❌ Don’ts
- Don’t use a
Checkboxwhen only one option is possible. In that case, use a Radio instead. - Don’t use checkboxes to trigger immediate actions such as submitting data.