Checkbox
<ahi-checkbox> | AhiCheckbox
Checkboxes are most commonly used to give users a way to make a range of selections (zero, one, or multiple). They may also be used as a way to have users indicate they agree to specific terms and services.
The checkbox is used in forms to toggle the state of something on or off. Default checkboxes can appear in two states: selected and disabled, or unselected.
<ahi-checkbox>Default</ahi-checkbox>
This component works with standard <form> elements. Please refer to the section on
form controls to learn more about form submission
and client-side validation.
Examples
Checkbox with help text
<ahi-checkbox help-text="Additional text to aid in use">Default</ahi-checkbox>
States
Disabled
Use the disabled attribute to disable a checkbox when another action has to be completed before
the checkbox is usable.
<ahi-checkbox disabled>Disabled</ahi-checkbox>
Checked
Use the checked attribute to set the initial selected state.
<ahi-checkbox checked>Checked</ahi-checkbox>
Indeterminate
Use the indeterminate attribute to make the checkbox indeterminate.
<ahi-checkbox indeterminate>Indeterminate</ahi-checkbox>
Keyboard support
-
Move focus to each checkbox using the
tabkey (orshift+tabwhen navigating backwards) - To interact with the checkbox when it has keyboard focus, press the
spacekey
Best practices
Checkboxes should:
- Work independently from each other: selecting one checkbox shouldn’t change the selection status of another checkbox in the list. The exception is when a checkbox is used to make a bulk selection of multiple items.
- Be listed according to a logical order, whether it’s alphabetical, numerical, time-based, or some other clear system
- Link to more information or include help text as required to provide more information. Don’t rely on tooltips to explain a checkbox.
- Use for “agreeing to the Terms of Service” and similar functionality.
Content guidelines
- Start all checkbox labels with a capital letter
- Keep checkbox labels short and descriptive
- Don’t include punctuation after checkbox labels
Related components
- To display a list of options where the user can only make a single selection, use radio buttons
- For a more compact way of displaying options, where users can only make a single selection, use a select
- To allow users to turn an option on or off, use a toggle
Importing
To import this component using a script tag:
<script type="module" src="/path/to/azalea-kit-ui/dist/components/checkbox/checkbox.js"></script>To import this component using a bundler:
import '@azaleahealth/azalea-kit-ui/dist/components/checkbox/checkbox.js';Slots
| Name | Description |
|---|---|
| (default) | The checkbox’s label. |
help-text
|
Additional text to aid in use. Alternatively, you can use the help-text attribute.
|
error
|
An error message shown once the control is invalid. Plain text can be set with the
error property instead; use this slot when the message needs markup.
|
Learn more about using slots.
Properties
| Name | Description | Type | Default | |
|---|---|---|---|---|
checked
|
Sets whether the checkbox is checked or unchecked. |
boolean
|
false
|
|
disabled
|
Sets whether the checkbox is disabled. |
boolean
|
false
|
|
helpText
help-text
|
Additional text to aid in use. |
string
|
''
|
|
indeterminate
|
Draws the checkbox in an indeterminate state. This is usually applied to checkboxes that represents a “select all/none” behavior when associated checkboxes have a mix of checked and unchecked states. |
boolean
|
false
|
|
name
|
The name of the checkbox, submitted as a name/value pair with form data. |
string
|
''
|
|
required
|
Makes the checkbox a required field. |
boolean
|
false
|
|
value
|
The current value of the checkbox, submitted as a name/value pair with form data. |
string
|
- | |
defaultChecked
|
The default value of the form control. Primarily used for resetting the form control. |
boolean
|
false
|
|
validity
|
Gets the validity state object | - | - | |
validationMessage
|
Gets the validation message | - | - | |
formId
form
|
By default, form controls are associated with the nearest containing
<form> element. This attribute allows you to place the form control outside of a
form and associate it with the form that has this id. The form must be in the same
document or shadow root for this to work.
|
string
|
''
|
|
form
|
The form the control is associated with, following the native form-control contract: reading returns
the associated <form> element (or null if there is none), assigning
takes a form id — assign an empty string to restore association with the nearest containing form.
|
HTMLFormElement | null
|
- | |
updateComplete |
A read-only promise that resolves when the component has finished updating. |
Learn more about properties and attributes.
Events
| Name | Description | Event Detail |
|---|---|---|
ahi-blur |
Emitted when the checkbox loses focus. | - |
ahi-change |
Emitted when the checked state changes. | - |
ahi-focus |
Emitted when the checkbox gains focus. | - |
ahi-input |
Emitted when the checkbox receives input. | - |
ahi-invalid |
Emitted when the form control has been checked for validity and its constraints aren’t satisfied. | - |
Learn more about events.
Methods
| Name | Description | Arguments |
|---|---|---|
click() |
Simulates a click on the checkbox. | - |
focus() |
Sets focus on the checkbox. |
options: FocusOptions
|
blur() |
Removes focus from the checkbox. | - |
checkValidity() |
Checks for validity but does not show a validation message. Returns true when valid and
false when invalid.
|
- |
reportValidity() |
Checks for validity and shows a validation message if the control is invalid. | - |
setCustomValidity() |
Sets a custom validation message. The value provided will be shown to the user when the form is submitted. To clear the custom validation message, call this method with an empty string. |
message: string
|
resetValidity() |
Hides validity again, returning the control to its pristine state: it stops matching
:user-invalid and drops its error styling until the user next interacts with it. The
value and the validity are both untouched — an empty required control is still invalid and still
blocks submission. This only changes whether that invalidity is shown. Interaction state
otherwise has exactly one automatic exit, form.reset(). Call this when the application
replaces a value itself and the old error no longer describes anything the user did: loading a
draft, switching which record is being edited, or clearing a filter row.
|
- |
Learn more about methods.
CSS Parts
| Name | Description |
|---|---|
base |
Deprecated. Use the checkbox part instead. |
checkbox |
The component’s outer wrapper. |
control |
The checkbox control. |
description |
The container for the label and help text. |
label |
The container that wraps the checkbox’s label. |
error |
The container that wraps the checkbox’s error icon and message. |
form-control-help-text |
The container that wraps the checkbox’s help text. This control inherits
setCustomValidity(message), checkValidity() and
reportValidity() from the form-control base class. Because they are inherited rather
than declared here, they do not appear in this component’s generated type definitions – which is why
they are easy to conclude do not exist. They do, and they work.
|
Learn more about customizing CSS parts.
Dependencies
This component automatically imports the following dependencies.
<ahi-icon>