Examples
Examples
Basic Usage
A label can be provided by nesting it inside the checkbox.
States
The Checkbox supports a wide range of different states.
Prefixes
The Checkbox accepts any content to be displayed as a decorative prefix such as images, texts, or other visual elements that help users to distinguish a group of options more clearly.
☝️ Watch out
The prefix is a decorative element only and should not contain any meaningful information necessary to understand or distinguish an option. Hence the content of a prefix isn't accessible to assistive technologies.
Help Text
The help text serves the purpose of guiding a user's decision by providing additional information.
Even though established as a common design pattern, checkbox labels should not contain any interactive elements like links as it is considered harmful to accessibility. Instead links to other resources should be provided using the help text.
A help text can either be passed as an attribute for simple string-based content or via a slot for rich formatted content.
Required and Optional
Adding a required or optional label helps users to be guided while filling out a form. Usually, only Checkboxes that are an exception to the majority of other form fields in a form are marked as required or optional. For example, a Checkbox is marked as "Required" when the majority of the fields in the same form are optional and vise versa.
Truncation
Checkboxes can be forced into a single line without compromising accessibility. The full content of the label is still associated with the Checkbox and is displayed after a view seconds on hover gesture.
💡 Did you know
Truncating a checkbox even works when used in conjunction with a Prefix.
Hit Area
When used as part of a group inside a container, the usability of Checkboxes can be improved by increasing their interactive hit area beyond the visible label covering the entire row. That allows users to make quick and easy selections across all options within a group without worrying about individual hit areas defined by varying label lengths.
Validation
A Checkbox's validity can either be determined automatically when used inside a form or can be controlled from outside based on custom rules and application business logic.
Inside a form
Checkboxes seamlessly integrate into a form's validation workflows and validate when a form is submitted. When no custom validation message is provided, the Checkbox falls back to the browser's native validation message.
Inside an application
Checkboxes can be individually flagged as invalid based on custom rules or other business logic of an application. When flagged as invalid, a Checkbox expects a descriptive validation message to be set alongside.
Listening to Events
The Checkbox supports the most commonly used events.
💡 Did you know?
Some native events like change are blocked by the Shadow DOM boundary of the web component standard. Hence some of them are proxied through custom events.
Find out more: Form Input Events & API
Validation API
Similar to the native one, Cosmos' Checkbox exposes public methods to interact with the validity state of the component. The methods are: inputCheckValidity, inputReportValidity and inputSetCustomValidity. The methods are asynchronous and must be waited for.