Checkbox

Checkboxes allow users to choose one or more items from a list of options, providing a convenient way to make selections. They typically appear in forms.

Usage

Code

Accessibility

Mathematics

Geography

Physics

History

<sl-form-field label="Subjects">
  <sl-checkbox-group value='["0","2"]'>
    <sl-checkbox value="0">Mathematics</sl-checkbox>
    <sl-checkbox value="1">Geography</sl-checkbox>
    <sl-checkbox value="2">Physics</sl-checkbox>
    <sl-checkbox value="3" disabled>History</sl-checkbox>
  </sl-checkbox-group>
</sl-form-field>

When to use

The following guidance describes when to use the Checkbox component.

Yes or No Decisions

Checkboxes simplify making yes-or-no decisions. Users can independently toggle options, whether it's about their preferences, agreeing to terms, or picking from a list.

Multiple Selections

When users need to pick multiple items from a list, checkboxes are a go-to. They offer flexibility, helping users select multiple choices or refine their search results.

Filtering and Sorting

Checkboxes are handy for users dealing with lots of options. They can fine-tune what they see by selecting specific attributes.

Only checkbox

When it becomes necessary to indicate to the user that certain elements have been selected. A practical instance would be the selection of a table’s row or a series of cards.

When not to use

The following guidance describes when not to use the Checkbox component.

Exclusive choices

While checkboxes work well in forms and filters, they're not suitable for exclusive selections. Instead, use radio buttons for single choices.

Toggle preferences

For actions that affect preferences or application behavior, opt for a switch for a better user experience.

Anatomy

Item	Name	Description	Optional
1	Field Label	The group label, positioned at the top of a checkbox group, provides a clear and concise description of the category or context for the choices contained within the group. It serves as a visual and informational cue that helps users understand the purpose of the options and facilitates more straightforward decision-making in the user interface. More information about group labels you can find in the Accessibility tab.	No
2	Checkbox input (unchecked)	An unchecked checkbox input is like a blank canvas. It represents an option or choice that is currently unselected, waiting for the user to make a decision and activate it.	No
3	Icon	The icon in a checkbox is a visual confirmation of user selection.	No
4	Label	A checkbox label is a brief, descriptive text next to the checkbox element.	Yes
5	Helper Text & Hint	The help text for a checkbox group is a informative component, it provides users with guidance and clarifications related to the available options. It assists users in making informed decisions by offering context, explanations, or additional details about the purpose or implications of the choices within the group. More information about help text you can find in the Accessibility tab.	Yes
6	Checkboxes	The checkbox group is designed with a minimum requirement of two options and allows a maximum of five selections. When the list of options exceeds this maximum limit, it's advisable to consider alternative design elements like a dropdown menu or combobox. These options provide a more user-friendly way to navigate and select from a larger set of choices, ensuring a streamlined and efficient user experience.	No

The medium checkbox serves as the default in our user interfaces. It strikes a balance between size and clarity, making it the standard and user-friendly option for binary decisions and multiple-choice selections within our applications.

Large

On touch-based devices, the large checkbox can be advantageous as it provides a bigger tap target, making it easier for users to interact with.

Status

The checkbox input facilitates multiple statuses, including unchecked, checked, and indeterminate. By default, a set of checkboxes the options are initially unchecked.

Checked

A checked checkbox serves as a visual confirmation of a user's selection or decision within a user interface. Its primary purpose is to indicate that a specific option or choice has been actively chosen or enabled. When a checkbox is checked, it communicates to the user that a particular action or preference is in effect.

Unchecked

An unchecked checkbox signals that a specific option or choice has not been selected or enabled by the user. Its primary purpose is to offer users the opportunity to make a binary decision as per their preference.

Indeterminate

The primary purpose of an indeterminate checkbox is to convey that the status of the associated options or sub-options is in a state of partial selection or indeterminacy. This can be particularly useful in scenarios where users are presented with a group of related choices, such as in a hierarchical list or nested categories. The indeterminate checkbox indicates that while some sub-options within the group are selected and some are not, the user can further refine their choices.

Variants

The default, valid, and invalid checkboxes play a pivotal role in offering users essential feedback on their interactions and guiding them toward necessary actions. These variants serve as visual indicators, providing users with clear cues about the status of their selections.

Default

The purpose of the default variant is to provide users with the option to select or deselect a choice or preference. When checked, it indicates an affirmative decision, and when unchecked, it signifies a negative choice.

Valid

A valid checkbox used in an online test serves as a feedback mechanism, confirming that the selected option or answer aligns with the correct choice, as defined by the test's criteria or answer key. When the valid checkbox is checked, it signals to the test-taker that their response is accurate and meets the assessment's requirements.

Invalid

This checkbox variant is prominently featured in form validation processes and tests. When checked, it communicates that there are significant issues or discrepancies in the entered data, prompting the user to review and rectify their input, ensuring data accuracy and a smooth user experience.

Figma Options

With these options, you can tweak the appearance of the checkbox in Figma. They are available in the Design Panel so you can compose the checkbox to exactly fit the user experience need for the use case you are working on.

Item	Options	Description
Size	`'md' (Default), 'lg'`	The checkbox and the label element come in two sizes: medium (default) and large, providing flexibility to align with your design requirements.
Variant	`'default', 'invalid', 'valid'`	This variants are provide to give feedback to the user about the interaction o the necessity of another action more.
States	`'idle', 'hover', 'active', 'disabled'`	Checkboxes interactive states to replicate the real behavior into your UI.
Status	`'Checked', 'Unchecked'`	To determinate between selected and unselect version.
Indeterminate	`'on', 'off'`	To turn the indeterminate state on or off.
Label	`'on', 'off'`	To turn to label on or off (label is turned on by default)
Label text	`'input text'`	To insert the text of the label.
Focus ring	`'on', 'off'`	Turn the focus ring option to show the focus state of the checkbox.

Behavior

Label overflow wrap

When a label is too long for the available horizontal space, it wraps to form another line, with the text aligned to the top.

Clickable area

The checkbox has a clickable area around both the checkbox and label for more space to press. We've left a bit of space on the left side to ensure smooth alignment and avoid any unexpected layout issues.

Focusable area

Both the checkbox input and label are interactive elements, allowing users to interact with them. However, when it comes to focusing, whether through keyboard navigation or voice commands, the visible focus state is only visible on the checkbox itself.

Validation

If an issue arises after submitting a form, the help text will switch to an 'invalid' state. This serves as a valuable guide for users, clearly explaining the necessary actions to resolve any problems.

Default checked

Set the initial state of the checkbox according to your preferences. You can choose whether it starts as checked or unchecked by default, providing you with control over its initial behavior in your interface.

Indeterminate State

Useful in scenarios where checkboxes are nested, we've incorporated an indeterminate state. Users can't set the indeterminate state by clicking on it, but it can be programmatically set to this state.

<form>
  <sl-checkbox value="yes">
    Checkbox
  </sl-checkbox>
  <sl-checkbox disabled value="yes" >
    Disabled
  </sl-checkbox>
  <sl-checkbox checked disabled value="yes">
    Disabled checked
  </sl-checkbox>
  <sl-checkbox show-validity="valid" checked valid value="yes">
    Valid
  </sl-checkbox>
  <sl-checkbox show-validity="invalid" checked invalid required value="yes">
    Invalid
  </sl-checkbox>
</form>

Checkbox group API

Checkbox group component provides properties to define the experience in different use cases, and it is a kind of wrapper for multiple checkboxes.

Properties

Name	Attribute	Type	Default	Description
`customValidity`	`custom-validity`	`string \| undefined`		The error message to display when the control is invalid.
`dirty`	-	`boolean`	`false`	A control is dirty if the user has changed the value in the UI.
`disabled`	`disabled`	`boolean \| undefined`		Whether the group is disabled; when set no interaction is possible.
`form`	-	`HTMLFormElement \| null`		The form associated with the control.
`formValue`	-	`unknown`		We need to override the setter as well, otherwise it won't work. See https://github.com/sl-design-system/components/issues/1441
`labels`	-	`NodeListOf<HTMLLabelElement>` \| null		The labels associated with the control.
`name`	`name`	`string \| undefined`		The name of the form control.
`nativeFormValue`	-	`FormValue`		Returns the form value as used in a native `<form>`. This is always a string, File, FormData or null.
`required`	`required`	`boolean \| undefined`		At least one checkbox in the group must be checked if true.
`showValid`	-	`boolean`	`false`	Optional property to indicate the valid state should be shown.
`showValidity`	`show-validity`	`'valid' \| 'invalid' \| undefined`		Whether to show the validity state.
`size`	`size`	`'sm' \| 'md' \| 'lg' \| undefined`		The size of the checkboxes in the group.
`touched`	-	`boolean`	`false`	A control is marked touched once the user has triggered a blur event on it.
`valid`	-	`boolean`		Returns whether the form control is valid or not.
`validationMessage`	-	`string`		String representing a localized (by the browser) message that describes the validation constraints that the control does not satisfy (if any). The string is empty if the control is not a candidate for constraint validation, or it satisfies its constraints. For true localization, see `getLocalizedValidationMessage()` instead.
`validity`	-	`ValidityState`		Returns the validity state the control is in.
`validityState`	-	`'valid' \| 'invalid' \| 'pending'`		Returns the current validity state.
`value`	`value`	`unknown \| undefined`		The value of the group.

Methods

Name	Parameters	Return	Description
`focus`		`void`
`reportValidity`		`boolean`	Returns whether the control is valid. If the control is invalid, calling this will also cause an `invalid` event to be dispatched. After calling this, the control will also report the validity to the user.
`reset`	`value: unknown`	`void`
`getLocalizedValidationMessage`		`string`	This returns a localized validation message. It does not support all `ValidityState` properties, since some require more context than we have here. If you need to support more, you can override this method in your own form control.
`setCustomValidity`	`message: string \| Promise<string>`	`void`	Sets a custom validation message for the form control. If the message is not an empty string, that will make the control invalid. By setting it to an empty string again, you can make the control valid again.

Events

Name	Event type	Description
`sl-blur`	`SlBlurEvent`	Emits when the component loses focus.
`sl-change`	`SlChangeEvent<Array<T \| null>>`	Emits when the value of the group changes.
`sl-focus`	`SlFocusEvent`	Emits when the component receives focus.
`sl-form-control`	`SlFormControlEvent`	Emits when the form control is added to the DOM.
`sl-update-state`	`SlUpdateStateEvent`	Emits when the UI state (dirty, pristine, touched or untouched) of the form control changes.
`sl-update-validity`	`SlUpdateValidityEvent`	Emits when the validity of the form control changes.
`sl-validate`	`SlValidateEvent`	Emits when the form control can be validated.

Slots

Name	Description
`default`	A list of `sl-checkbox` elements.

Checkbox API

Checkbox component has a range of properties, attributes etc. to define the experience in different use cases, and it can be used as the replacement of the HTML native checkbox.

Properties

Name	Attribute	Type	Default	Description
`checked`	`checked`	`boolean \| undefined`		Whether the checkbox is checked.
`customValidity`	`custom-validity`	`string \| undefined`		The error message to display when the control is invalid.
`dirty`	-	`boolean`	`false`	A control is dirty if the user has changed the value in the UI.
`disabled`	`disabled`	`boolean \| undefined`		Whether the checkbox is disabled; when set no interaction is possible.
`form`	-	`HTMLFormElement \| null`		The form associated with the control.
`formValue`	-	`unknown`		The value used when submitting the form.
`indeterminate`	`indeterminate`	`boolean \| undefined`		Whether the checkbox has the indeterminate state.
`input`	-	`HTMLInputElement`		The input element in the light DOM.
`labels`	-	`NodeListOf<HTMLLabelElement>` \| null		The labels associated with the control.
`name`	`name`	`string \| undefined`		The name of the form control.
`nativeFormValue`	-	`FormValue`		Returns the form value as used in a native `<form>`. This is always a string, File, FormData or null.
`required`	`required`	`boolean \| undefined`		Whether the checkbox is required.
`showValid`	`show-valid`	`boolean`	`false`	When set will cause the control to show it is valid after reportValidity is called.
`showValidity`	`show-validity`	`'valid' \| 'invalid' \| undefined`		Whether to show the validity state.
`size`	`size`	`'sm' \| 'md' \| 'lg'`	`'md'`	The size of the checkbox.
`touched`	-	`boolean`	`false`	A control is marked touched once the user has triggered a blur event on it.
`valid`	-	`boolean`		Returns whether the form control is valid or not.
`validationMessage`	-	`string`		String representing a localized (by the browser) message that describes the validation constraints that the control does not satisfy (if any). The string is empty if the control is not a candidate for constraint validation, or it satisfies its constraints. For true localization, see `getLocalizedValidationMessage()` instead.
`validity`	-	`ValidityState`		Returns the validity state the control is in.
`validityState`	-	`'valid' \| 'invalid' \| 'pending'`		Returns the current validity state.
`value`	`value`	`unknown \| undefined`		The value of the checkbox when the checkbox is checked. See the formValue property for easy access.

Methods

Name	Parameters	Return	Description
`focus`		`void`
`getLocalizedValidationMessage`		`string`	This returns a localized validation message. It does not support all `ValidityState` properties, since some require more context than we have here. If you need to support more, you can override this method in your own form control.
`reportValidity`		`boolean`	Returns whether the control is valid. If the control is invalid, calling this will also cause an `invalid` event to be dispatched. After calling this, the control will also report the validity to the user.
`reset`	`value: unknown`	`void`
`setCustomValidity`	`message: string \| Promise<string>`	`void`	Sets a custom validation message for the form control. If the message is not an empty string, that will make the control invalid. By setting it to an empty string again, you can make the control valid again.

Events

Name	Event type	Description
`sl-blur`	`SlBlurEvent`	Emits when the component loses focus.
`sl-change`	`SlChangeEvent<T \| null>`	Emits when the checked state changes.
`sl-focus`	`SlFocusEvent`	Emits when the component receives focus.
`sl-form-control`	`SlFormControlEvent`	Emits when the form control is added to the DOM.
`sl-update-state`	`SlUpdateStateEvent`	Emits when the UI state (dirty, pristine, touched or untouched) of the form control changes.
`sl-update-validity`	`SlUpdateValidityEvent`	Emits when the validity of the form control changes.
`sl-validate`	`SlValidateEvent`	Emits when the form control can be validated.

Slots

Name	Description
`default`	Text label of the checkbox. Technically there are no limits what can be put here; text, images, icons etc.
`input`	The slot for the input element

CSS Parts

Name	Description
	outer - The outer container of the checkbox
	inner - The inner container of the checkbox
	label - The label of the checkbox

Having an accessible application is not only achieved by writing good code, but also (maybe even MORE so) by writing good copy. To make sure checkbox groups and their options are clear for all users make sure to keep these points in mind:

Group labels

Positioned above checkbox groups to ensure clear organization when multiple checkboxes share a common category. They must effectively convey the common theme while maintaining a balance between brevity and descriptiveness for user clarity.

By following the tips below, you can write group labels that effectively categorize checkboxes.

Conciseness

Keep the label concise. Use as few words as possible while still conveying the primary purpose or theme of the checkboxes in the group.

Descriptive Clarity

While being concise, ensure the label provides enough information to make it clear what the checkboxes within the group represent. Use descriptive language that leaves no ambiguity.

User-Centered Language

Use language that your target audience can easily understand. Avoid complex terminology or jargon that might confuse users.

Consistency

Maintain a consistent style and wording for group labels throughout your interface. This creates a cohesive design and makes it easier for users to understand the organization.

Checkbox labels

Positioned alongside individual checkboxes, checkbox labels play a pivotal role in user understanding and interaction. Follow these tips for creating clear and user-friendly checkbox labels:

Conciseness

Keep the label concise. Use as few words as necessary to convey the checkbox's primary purpose or action.

Descriptive Clarity

While being concise, ensure the label provides enough information to make it clear what the checkbox represents or the action it triggers. Use descriptive language that leaves no room for ambiguity.

User-Centered Language

Use language that your target audience can easily understand. Avoid using technical jargon or industry-specific terms that might confuse users.

No Negative Statements

Avoid using negative statements that might confuse users, such as "checking the checkbox to turn off" or "opt-out." Instead, positively frame the label.

Avoid Mixing "Enable" and "Disable" Options

In a group of checkboxes, maintain consistency by not mixing "enable" and "disable" options. Users should easily discern the purpose of each checkbox.

Consistency

Ensure that all options in a group have the same form or category. Avoid mixing unrelated categories (e.g., nationalities and countries) within the same checkbox group.

Sorting Options

When presenting checkboxes in a group, consider sorting them logically. You can arrange them alphabetically or by importance.

Help text

Positioned beneath checkbox groups, help text offers valuable context and guidance. Follow these tips to craft informative and user-friendly help text:

Conciseness

Keep the help text brief, using only 1-2 short, complete sentences. Avoid unnecessary verbosity to maintain clarity.

Descriptive Clarity

While being concise, ensure the help text provides clear and informative guidance. Explain what happens when the user selects the option, ensuring they understand the consequences or benefits associated with their choice.

User-Centered Language

Use language that aligns with your target audience. Avoid technical jargon or industry-specific terms that might confuse users.

No Repetition

Avoid merely restating the label in different phrasing within your help text. Instead, focus on providing additional context and information that enhances the user's understanding.

Consistency

Maintain a consistent style and tone throughout your help text. This consistency aids users in understanding and interacting with your interface.

Keyboard interactions

Keyboard interaction with a checkbox refers to how users can interact with checkboxes using keyboard inputs. Typically, users can navigate to a checkbox using the "Tab" key, select or deselect it with the "Spacebar" key, and sometimes use other keyboard shortcuts for efficiency. Keyboard interaction ensures that individuals who rely on keyboard navigation or assistive technologies can easily control checkboxes within a user interface. We use a tab to switch between checkbox groups to enable faster navigation in a form; when you want to navigate to the "Save" button quickly, you shouldn't be required to go over the complete list of options just to get to the end of the form.

Command	Description
Tab	Shifts focus to the first checkbox input in a checkbox group or a checkbox that isn't in a group.
Space/Enter	Toggles the checkbox between checked and unchecked states.
Arrow Keys	Once you are in a checkbox group you can navigate to the next checkbox by using the right or down arrow key. You can navigate back to the previous box with left or up. The focus indicator loops, so when you are at the last option and press "down" it will focus on the first option.

WAI-ARIA

WAI-ARIA Roles, States, and Properties for a checkbox provide essential information to assistive technologies and screen readers. They convey the checkbox's role, state (checked or unchecked), and additional properties to ensure accessibility and a better user experience for individuals using assistive technology.

Checkbox

Attribute	Value	Description	User suppliedSpecifies whether the attribute is always set in the component (no) or it needs to be provided by the developer (yes)
`aria-checked`	`'true','false','mixed'`	The state of the checkbox.	no
`role`	`'checkbox'`	Declare our custom component as a checkbox.	no
`aria-label`	string	Can be added when the checkbox doesn't have a label text.	yes
`aria-describedby`	string	Used to describe (link with) hint (helper text) and/or error message.	no
`aria-disabled`	boolean	Announces the checkbox component as disabled with a screen reader. See [Note 1] below.	yes
`aria-labelledby`	string	When multiple checkboxes are used to connect with single header that describes checkboxes.	yes

Checkbox group

Attribute	Value	Description	User supplied
`role`	`'group'`	Declare our group of custom checkbox components as a checkbox group.	no
`aria-label`	string	Can be added when there is no label or header that could be described by.	yes
`aria-describedby`	string	Used to describe (link with) hint (helper text) and/or error message.	no
`aria-labelledby`	string	Used to connect with single header that describes checkbox group, when there is no label component connected to.	yes

Notes:

The aria-disabled should not be used as a one-for-one replacement for the disabled attribute because they have different functionalities:

disabled dims the checkbox visually, takes it out of the tab-focus sequence, prevents actions (click, enter) on it and announces it as 'dimmed' or 'disabled' in a screen reader.
aria-disabled only does the latter. You will need to disable the functionality yourself. This might be useful for scenarios where you don't want to take the checkbox out of the navigation flow.

When disabled is added to a checkbox there is no need to also add aria-disabled. Everything aria-disabled does, disabled does as well. You can read more on the difference and in which scenarios which option might be preferable on the MDN page about aria-disabled.

Interactive example