Vivid API

Checkbox

Checkboxes allow users to select one or more items from a list of options.

Usage

import { VCheckbox } from '@vonage/vivid-api-vue';
import { registerCheckbox } from '@vonage/vivid-api';
registerCheckbox('your-prefix');

Checkbox follows the W3C specification for <input type="checkbox">.

Controlling State

Aria Checked

As an alternative to the checked and indeterminate members, you can use the aria-checked attribute to set the Checkbox’s checked state. It reflects the checked state as well as the indeterminate state with the value “mixed”.

The ariaChecked property of the Element interface reflects the value of the aria-checked attribute, which indicates the current “checked” state of checkboxes. A string with one of the following values: “true” The element is checked. “mixed” Indicates a mixed mode value for a tri-state checkbox. “false” The element supports being checked but is not currently checked. “undefined” The element does not support being checked. — mdn

The aria-checked prop will no longer set the state (as of 06/25) . It is still functional in the component, but will be updated in a future major release. This will be communicated when it’s change becomes a release candidate at the end of the support period.

Slots

Default

The default slot allows you to use rich content as the Checkbox’s label.

Helper Text

The helper-text slot allows you to use rich content as the Checkbox’s helper text.

API Reference

Properties

PropertyTypeDefaultDescription
checked
(modelValue)
booleanThe current checkedness of the element.
connotation'accent' | 'cta'The connotation the checklist should have.
defaultCheckedbooleanThe default checkedness of the element. This value sets the `checked` property only when the `checked` property has not been explicitly set.
disabledbooleanSets the element's disabled state. A disabled element will not be included during form submission.
errorTextstringProvides a custom error message. Any current error state will be overridden.
helperTextstringProvides additional information to help the user enter the correct information. To add HTML to the helper text, use the helper-text slot instead.
indeterminatebooleanIndicates whether a checkbox is in an indeterminate state.
initialValuestringThe default value of the element. This value sets the `value` property only when the `value` property has not been explicitly set.
labelstringThe label for the form element.
namestringThe name of the element. This element's value will be surfaced during form submission under the provided name.
readOnlybooleanWhen true, the control will be immutable by user interaction. See https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/readonly | readonly HTML attribute for more information.
requiredbooleanRequire the field to be completed prior to form submission.
successTextstringProvides a custom success message. Any current error state will be overridden.
tabindexstring
valuestringThe current value of the element.
PropertyTypeDefaultDescription
current-checkedbooleanThe current checkedness of the element.
connotation'accent' | 'cta'The connotation the checklist should have.
checkedbooleanThe default checkedness of the element. This value sets the `checked` property only when the `checked` property has not been explicitly set.
disabledbooleanSets the element's disabled state. A disabled element will not be included during form submission.
error-textstringProvides a custom error message. Any current error state will be overridden.
helper-textstringProvides additional information to help the user enter the correct information. To add HTML to the helper text, use the helper-text slot instead.
indeterminatebooleanIndicates whether a checkbox is in an indeterminate state.
valuestringThe default value of the element. This value sets the `value` property only when the `value` property has not been explicitly set.
labelstringThe label for the form element.
namestringThe name of the element. This element's value will be surfaced during form submission under the provided name.
readonlybooleanWhen true, the control will be immutable by user interaction. See https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/readonly | readonly HTML attribute for more information.
requiredbooleanRequire the field to be completed prior to form submission.
success-textstringProvides a custom success message. Any current error state will be overridden.
tabindexstring
current-valuestringThe current value of the element.

Slots

NameDescription
defaultThe default slot allows you to use rich content as the checkbox's label.
helper-textDescribes how to use the checkbox. Alternative to the `helper-text` attribute.
NameDescription
defaultThe default slot allows you to use rich content as the checkbox's label.
helper-textDescribes how to use the checkbox. Alternative to the `helper-text` attribute.

Events

NameTypeDescription
changeCustomEvent<undefined>Emitted when the checked state changes.
inputCustomEvent<undefined>Emitted when the checked state changes.
NameTypeDescription
changeCustomEvent<undefined>Emitted when the checked state changes.
inputCustomEvent<undefined>Emitted when the checked state changes.

Methods

NameParamsReturnsDescription
checkValiditybooleanReturn the current validity of the element.
reportValiditybooleanReturn the current validity of the element. If false, fires an invalid event at the element.