Checkbox
Checkboxes allow users to select one or more items from a list of options.
import { VCheckbox } from '@vonage/vivid-vue';
import { registerCheckbox } from '@vonage/vivid';
registerCheckbox('your-prefix');
Checkbox follows the W3C specification for <input type="checkbox">.
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.
The default slot allows you to use rich content as the Checkbox's label.
The helper-text slot allows you to use rich content as the Checkbox's helper text.
| Property | Type | Default | Description |
|---|---|---|---|
| checked (modelValue) |
boolean |
The current checkedness of the element. | |
| connotation | 'accent' | 'cta' |
The connotation the checklist should have. | |
| defaultChecked | boolean |
The default checkedness of the element. This value sets the `checked` property only when the `checked` property has not been explicitly set. | |
| disabled | boolean |
Sets the element's disabled state. A disabled element will not be included during form submission. | |
| errorText | string |
Provides a custom error message. Any current error state will be overridden. | |
| helperText | string |
Provides additional information to help the user enter the correct information. To add HTML to the helper text, use the helper-text slot instead. | |
| indeterminate | boolean |
Indicates whether a checkbox is in an indeterminate state. | |
| initialValue | string |
The default value of the element. This value sets the `value` property only when the `value` property has not been explicitly set. | |
| label | string |
The label for the form element. | |
| name | string |
The name of the element. This element's value will be surfaced during form submission under the provided name. | |
| readOnly | boolean |
When 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. | |
| required | boolean |
Require the field to be completed prior to form submission. | |
| successText | string |
Provides a custom success message. Any current error state will be overridden. | |
| tabindex | string |
||
| value | string |
The current value of the element. |
| Property | Type | Default | Description |
|---|---|---|---|
| current-checked | boolean |
The current checkedness of the element. | |
| connotation | 'accent' | 'cta' |
The connotation the checklist should have. | |
| checked | boolean |
The default checkedness of the element. This value sets the `checked` property only when the `checked` property has not been explicitly set. | |
| disabled | boolean |
Sets the element's disabled state. A disabled element will not be included during form submission. | |
| error-text | string |
Provides a custom error message. Any current error state will be overridden. | |
| helper-text | string |
Provides additional information to help the user enter the correct information. To add HTML to the helper text, use the helper-text slot instead. | |
| indeterminate | boolean |
Indicates whether a checkbox is in an indeterminate state. | |
| value | string |
The default value of the element. This value sets the `value` property only when the `value` property has not been explicitly set. | |
| label | string |
The label for the form element. | |
| name | string |
The name of the element. This element's value will be surfaced during form submission under the provided name. | |
| readonly | boolean |
When 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. | |
| required | boolean |
Require the field to be completed prior to form submission. | |
| success-text | string |
Provides a custom success message. Any current error state will be overridden. | |
| tabindex | string |
||
| current-value | string |
The current value of the element. |
| Name | Description |
|---|---|
| default | The default slot allows you to use rich content as the checkbox's label. |
| helper-text | Describes how to use the checkbox. Alternative to the `helper-text` attribute. |
| Name | Description |
|---|---|
| default | The default slot allows you to use rich content as the checkbox's label. |
| helper-text | Describes how to use the checkbox. Alternative to the `helper-text` attribute. |
| Event | Type | Description |
|---|---|---|
| change | CustomEvent<undefined> |
Emitted when the checked state changes. |
| input | CustomEvent<undefined> |
Emitted when the checked state changes. |
| update:modelValue | boolean |
Fires when the modelValue value changes |
| Name | Type | Description |
|---|---|---|
| change | CustomEvent<undefined> |
Emitted when the checked state changes. |
| input | CustomEvent<undefined> |
Emitted when the checked state changes. |
| Name | Params | Returns | Description |
|---|---|---|---|
| checkValidity |
boolean
|
Return the current validity of the element. | |
| reportValidity |
boolean
|
Return the current validity of the element. If false, fires an invalid event at the element. |