Checkboxes provide a UI element for toggling between two visual states, checked and unchecked. They can be labelled with text to explain the semantics of the checked state to users. Checkboxes can be used in HTML forms as well as React controlled components.
For grouping multiple related checkboxes in a style-guide-conformant fashion see <axa-fieldset>.
Unless otherwise noted, properties can be set via attributes or properties. Starred property names are reflected to attributes.
The string-valued name of the checkbox for purposes of form submission.
The string-valued value of the checkbox for purposes of form submission.
The string-valued label provides the label text. When no label is set and the component has no children, no <label> will be rendered for reasons of semantic HTML.
HTML markup is permitted as value, subject to being single-rooted (see below). Such label values must respect the specification.
A label value can also be specified via the component's children. Note that such HTML child content must be single-rooted, and that <label> is not a permissible child root (to prevent improper nesting with the element-provided <label>). The component wraps its children in <p> for accessibility.
Note: The use of component children for label specification is discouraged for technical reasons. We recommend styled HTML labels instead.
The Boolean attribute styled, when used in conjunction with HTML-valued label, ensures that the styling of such labels is appropriate.
| Attribute | Details |
|---|---|
variant="square" |
Provides a filled square in the icon (default) |
variant="checkmark" |
Provides a checkmark in the icon |
variant="checkmark-inverted" |
Provides a checkmark in the icon with inverted color. Just use it if you have background-color "blue-teal". |
The string-valued refId sets the reference ID for label and input. If no refId is set, a random ID will be created.
The Boolean attribute required visualizes an element that must obligatorily be filled by the user. When true, displays * after the label text.
The Boolean checked sets the checked/unchecked visual state.
The Boolean defaultChecked sets the initial checked state. It is only available under React.
The Boolean disabled disables the checkbox natively.
The string-valued error provides an error text as HTML. It sets the checkbox into a visual error state.
The function-valued property onChange can be used as a callback prop for React and other frameworks. Its only parameter is the corresponding native event from the underlying <input> element.
It is especially significant when used together with value to implement controlled-component
behaviour under React.
The function-valued property onFocus can be used as a callback prop for React and other frameworks.
Its only parameter is the corresponding native event from the underlying <input> element.
The function-valued property onBlur can be used as a callback prop for React and other frameworks.
Its only parameter is the corresponding native event from the underlying <input> element.