Checkbox
A box the user checks to say yes to one thing, or to pick several options of a list.
Showcase
<LnxCheckbox v-model="..." <-- Pass a reactive variable here to bind its value @update:modelValue="..." <-- Two way binding of the component > I accept the terms </LnxCheckbox>
v-model
boolean | T[]A boolean, or an array to add and remove the `value` of the checkbox, like a native one Default value: undefinedcustomValidity
stringThe error message of the checkbox. It is the default value for the `error` slot Default value: undefinedindeterminate
booleanShows a dash instead of a check, for a group partly checked. It's read out as "mixed" Default value: falseWhen to use
- For one yes or no that the user confirms with a form, like accepting terms.
- For several options of a short list. With many options, or to show them as chips, use a RadioGroup with
multiple. - For a setting that applies at once, use a Switch.
Examples
Yes or no
With a boolean v-model. A click on the label checks it too, and so does the space bar when it has the focus. A long label wraps with the box on its first line.
false
vue
<LnxCheckbox v-model="accepted">
Send me a summary of the minutes after every meeting of the board, with the agreements and the votes
</LnxCheckbox>
<span>{{ accepted }}</span>1
2
3
4
2
3
4
Several options
With an array v-model, each checkbox adds or removes its value. indeterminate shows that only some are checked.
[
"email"
]
vue
<LnxCheckbox v-model="allChannels" :indeterminate="channels.length > 0 && !allChannels">
All channels
</LnxCheckbox>
<LnxCheckbox v-for="channel in CHANNELS" :key="channel" v-model="channels" :value="channel" style="margin-left: 26px">
{{ channel }}
</LnxCheckbox>
<span>{{ channels }}</span>1
2
3
4
5
6
7
2
3
4
5
6
7
Required
Attributes go to the native <input>, so required works with the validation of the form.
vue
<form @submit.prevent>
<LnxCheckbox v-model="terms" required has-error custom-validity="You need to accept the terms">
I accept the terms
</LnxCheckbox>
<LnxButton type="submit">Send</LnxButton>
</form>1
2
3
4
5
6
2
3
4
5
6
API
Props
| Prop | Type | Description |
|---|---|---|
v-model | boolean | T[] | A boolean, or an array to add and remove the value of the checkbox, like a native one |
is-loading | boolean | When loading, it is disabled and shows a spinner in the box Default: false |
has-error | boolean | Indicates if it should show the error slot Default: false |
custom-validity | string | The error message of the checkbox. It is the default value for the error slot |
indeterminate | boolean | Shows a dash instead of a check, for a group partly checked. It's read out as "mixed" Default: false |
Events
| Event | Payload | Description |
|---|---|---|
update:modelValue | boolean | T[] | Two way binding of the component |
Slots
| Slot | Scope | Description |
|---|---|---|
default | — | The label of the checkbox |
helper | — | Message below the checkbox to add extra context |
error | — | Message shown when the checkbox has an error |
Accessibility
- It's a native checkbox: the space bar checks it and the label names it.
indeterminateis read out as "mixed".- The
customValiditymessage is set as the native validity, so the form won't submit while it's shown.