Checkbox
A choice that a submit will carry out, as opposed to a switch, which acts at once. It wraps a real <input type="checkbox">, so it submits with the form.
Usage
Examples
Hint
label writes the text beside the box, and the default slot replaces it when the label needs more than text. hint adds a caption underneath, tied to the box through aria-describedby and kept outside the <label>, so it is announced as a description rather than as part of the name.
Label position
labelPosition moves the label before the box instead of after it.
Spread
spread takes the full width offered and pushes the label and the box to opposite ends of the row.
Indeterminate
indeterminate shows a dash instead of a tick. It is an appearance of its own: the v-model still holds true or false.
Read-only
readonly shows the state without letting it change. The native attribute does nothing on a checkbox, so the component cancels the click, which covers Space as well. The box stays focusable, is submitted with its form and is announced as read-only. It still takes part in constraint validation, though, so readonly with required and nothing ticked leaves a form that cannot be submitted or fixed.
Disabled
disabled prevents the box from being ticked and greys it out through the colour tokens. The keyboard steps over it.
API
Props
| Prop | Type | Default |
|---|---|---|
label | string | none |
| The text beside the box, which names it. The default slot replaces it. | ||
hint | string | none |
| A line of help under the label. It is tied to the checkbox for assistive technology, so it is read out after the label rather than as part of it. | ||
indeterminate | boolean | false |
| Shows the box as partially checked, a dash instead of a tick. This is what a parent checkbox looks like when some of its children are ticked and others are not. It is a state of its own, not a value the v-model can hold. | ||
labelPosition | CheckboxLabelPosition'start' | 'end' | 'end' |
| Which side of the box the label sits on. | ||
spread | boolean | false |
| Pushes the label and the box to opposite ends of the line, the row taking the full width available. This is the usual shape for a list of settings. | ||
invalid | boolean | false |
| Marks the field as invalid, which colours the box and tells assistive technology so. Use it for a rule the browser cannot check by itself; native validity is already handled without it. | ||
disabled | boolean | false |
| Makes the checkbox unusable, greyed out through the colour tokens. | ||
readonly | boolean | false |
| Shows the state without allowing it to be changed. The checkbox can still be focused, is announced as read-only and is still submitted with its form; a click or the Space key simply changes nothing. | ||
v-model | boolean | false |
Whether the box is ticked. It starts unticked, and the dash is a third appearance rather than a third value: that one is indeterminate. | ||
Slots
| Slot | Type |
|---|---|
default | {} |
The label, when it needs more than the label prop's text. It is clickable. | |
CSS variables
| Token | Value |
|---|---|
--vectis-control-size-check | 1.25rem |
--vectis-control-size-check-mark | 0.875rem |