Checkbox <va-checkbox>
Lets the user choose an option, or agree to something, as part of a form.
When to use it
- Use it
- For an option submitted with a form, for agreeing to terms, or to select items in a list.
- Don't use it
- For a setting that should apply immediately.
- Use instead
va-switch for settings that take effect immediately.
Examples
Options
A checkbox's label is its slotted text; help text goes in the description slot.
Include archived projects
Send me a copy
We'll email it to the address on your account.
Select all (some selected)
Not available on your plan
<va-checkbox checked>Include archived projects</va-checkbox>
<va-checkbox>
Send me a copy
<span slot="description">We'll email it to the address on your account.</span>
</va-checkbox>
<va-checkbox indeterminate>Select all (some selected)</va-checkbox>
<va-checkbox disabled>Not available on your plan</va-checkbox>
Required, in a form
A required checkbox blocks submit until it is checked, like a native one.
<form>
<va-checkbox name="terms" value="accepted" required>I agree to the terms</va-checkbox>
<va-button type="submit">Create account</va-button>
</form>
Install and import
npm install @firstprateek/vastu @firstprateek/vastu-tokens
import '@firstprateek/vastu-tokens/lekha.css'; // once per page
import '@firstprateek/vastu/checkbox';
API
Attributes and properties
| Attribute | Property | Type | Default | Description |
|---|
checked | checked | boolean | false | Whether the box is checked. |
indeterminate | indeterminate | boolean | false | Shows a dash for a partly selected group. Cleared when the user toggles the box. |
value | value | string | 'on' | Submitted with name while the box is checked. Defaults to on, as for a native checkbox. |
label | label | string | '' | Accessible name, when there is no visible label text. |
name | name | string | '' | Submitted with the form as name=value. |
disabled | disabled | boolean | false | Disables the control. It can't be focused, changed or submitted. |
required | required | boolean | false | The control must have a value before its form can be submitted. |
| — | form (read-only) | HTMLFormElement | null | — | The form this control belongs to, if any. |
| — | validity (read-only) | ValidityState | — | The control's validity state, as on native controls. |
| — | validationMessage (read-only) | string | — | The message the browser shows when the control is invalid, or an empty string. |
Events
| Event | Description |
|---|
change | When the user checks or unchecks the box. Read event.target.checked. |
input | When the user checks or unchecks the box, just before change. |
Slots
| Slot | Description |
|---|
| (default) | The visible label. Clicking it toggles the checkbox. |
description | Optional help text under the label. |
Methods
| Method | Description |
|---|
checkValidity() | Returns true if the control is valid; otherwise fires invalid and returns false. |
reportValidity() | Like checkValidity(), but also shows the browser's message to the user. |
Styling
Components read the brand's tokens. To adjust one component, set its custom properties or style its parts.
| Custom property | Type | Description |
|---|
--va-checkbox-border | <color> | Border colour of the box. |
--va-checkbox-checked | <color> | Fill colour when checked or indeterminate. |
--va-checkbox-mark | <color> | Colour of the tick or dash. |
--va-checkbox-size | <length> | Width and height of the box. |
| Part | Description |
|---|
::part(control) | The square box. |
::part(label) | The label text. |
Accessibility
- Role
checkbox- Accessible name
- The slotted label text, or the
label attribute when there is no visible label. - Note
indeterminate is announced as "mixed", for a box that stands for a partly selected group.
Keyboard
| Key | Does |
|---|
| Space | Checks or unchecks the box. |
| Tab | Moves focus to the next control. |
Every row on this page is checked by contract tests generated from the same manifest, in Chromium, Firefox and WebKit. Read the manifest.