Vastu

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.

I agree to the terms Create account
<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

AttributePropertyTypeDefaultDescription
checkedcheckedbooleanfalseWhether the box is checked.
indeterminateindeterminatebooleanfalseShows a dash for a partly selected group. Cleared when the user toggles the box.
valuevaluestring'on'Submitted with name while the box is checked. Defaults to on, as for a native checkbox.
labellabelstring''Accessible name, when there is no visible label text.
namenamestring''Submitted with the form as name=value.
disableddisabledbooleanfalseDisables the control. It can't be focused, changed or submitted.
requiredrequiredbooleanfalseThe 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

EventDescription
changeWhen the user checks or unchecks the box. Read event.target.checked.
inputWhen the user checks or unchecks the box, just before change.

Slots

SlotDescription
(default)The visible label. Clicking it toggles the checkbox.
descriptionOptional help text under the label.

Methods

MethodDescription
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 propertyTypeDescription
--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.
PartDescription
::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

KeyDoes
SpaceChecks or unchecks the box.
TabMoves 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.