Checkbox
<terra-checkbox> | TerraCheckbox
Checkboxes are a form field used when there are multiple options to select from a list.
<terra-checkbox>Articles</terra-checkbox>
Examples
Basic Checkbox
Checkboxes always include a label and are stacked vertically to form a list of options.
<div style="display: flex; flex-direction: column; gap: 0.75rem;"> <terra-checkbox>Articles</terra-checkbox> <terra-checkbox>Features</terra-checkbox> <terra-checkbox>Press Releases</terra-checkbox> </div>
Checked State
Use the checked attribute to set the initial checked state.
<div style="display: flex; flex-direction: column; gap: 0.75rem;"> <terra-checkbox checked>Articles</terra-checkbox> <terra-checkbox>Features</terra-checkbox> <terra-checkbox checked>Press Releases</terra-checkbox> </div>
Sizes
Checkboxes come in three sizes: small, medium (default), and large.
<div style="display: flex; flex-direction: column; gap: 0.75rem;"> <terra-checkbox size="small">Small</terra-checkbox> <terra-checkbox size="medium">Medium</terra-checkbox> <terra-checkbox size="large">Large</terra-checkbox> </div>
Indeterminate State
The indeterminate state is useful for “select all/none” scenarios when associated checkboxes have a mix of checked and unchecked states.
<div style="display: flex; flex-direction: column; gap: 0.75rem;"> <terra-checkbox indeterminate>Select All</terra-checkbox> <terra-checkbox checked>Articles</terra-checkbox> <terra-checkbox>Features</terra-checkbox> <terra-checkbox checked>Press Releases</terra-checkbox> </div>
Required Field
Use the required attribute to mark a checkbox as required. The label will display an
asterisk.
<div style="display: flex; flex-direction: column; gap: 0.75rem;"> <terra-checkbox required>I agree to the terms and conditions</terra-checkbox> <terra-checkbox>Subscribe to newsletter (optional)</terra-checkbox> </div>
Disabled State
Use the disabled attribute to disable a checkbox.
<div style="display: flex; flex-direction: column; gap: 0.75rem;"> <terra-checkbox disabled>Disabled unchecked</terra-checkbox> <terra-checkbox disabled checked>Disabled checked</terra-checkbox> </div>
Help Text
Use the help-text attribute or slot to provide additional guidance.
<div style="display: flex; flex-direction: column; gap: 0.75rem;"> <terra-checkbox help-text="Select all content types you want to see"> Content Types </terra-checkbox> <terra-checkbox> Articles <span slot="help-text">Published articles and blog posts</span> </terra-checkbox> </div>
Form Integration
Checkboxes work seamlessly with native HTML forms.
<form id="filter-form"> <fieldset> <legend>Filter by Content Type</legend> <div style="display: flex; flex-direction: column; gap: 0.75rem; margin-top: 0.5rem;"> <terra-checkbox name="content-type" value="articles">Articles</terra-checkbox> <terra-checkbox name="content-type" value="features">Features</terra-checkbox> <terra-checkbox name="content-type" value="press-releases">Press Releases</terra-checkbox> </div> </fieldset> </form>
Best Practices
- Always include labels: Checkboxes should always have a clear, descriptive label that explains what the option does.
- Stack vertically: When multiple checkboxes are used together, stack them vertically to form a clear list of options.
- Use for multiple selections: Checkboxes allow users to select zero, one, or multiple options. For mutually exclusive choices, use Radio Buttons instead.
- Group related options: Use a fieldset and legend to group related checkboxes, especially in forms.
- Indicate required fields: If only some fields in a form are required, indicate required checkbox fields with an asterisk. If most fields are required, indicate optional fields by displaying ”(optional)” next to the label.
- Provide help text when needed: Use help text to clarify what selecting an option will do, especially for filtering or settings.
Accessibility
- Checkboxes are keyboard accessible and can be activated with the Space key
- The component properly associates labels with the checkbox input
- Focus states are clearly visible with a focus ring
- Required fields are indicated with an asterisk
- Help text is properly associated with the checkbox using
aria-describedby
[component-metadata:terra-checkbox]
Importing
If you’re using the autoloader or the traditional loader, you can ignore this section. Otherwise, feel free to use any of the following snippets to cherry pick this component.
To import this component from the CDN using a script tag:
<script type="module" src="https://cdn.jsdelivr.net/npm/@nasa-terra/components@0.0.138/cdn/components/checkbox/checkbox.js"></script>
To import this component from the CDN using a JavaScript import:
import 'https://cdn.jsdelivr.net/npm/@nasa-terra/components@0.0.138/cdn/components/checkbox/checkbox.js';
To import this component using a bundler:
import '@nasa-terra/components/dist/components/checkbox/checkbox.js';
To import this component as a React component:
import TerraCheckbox from '@nasa-terra/components/dist/react/checkbox';
Slots
| Name | Description |
|---|---|
| (default) | The checkbox’s label. |
help-text
|
Text that describes how to use the checkbox. Alternatively, you can use the
help-text attribute.
|
Learn more about using slots.
Properties
| Name | Description | Reflects | Type | Default |
|---|---|---|---|---|
name
|
The name of the checkbox, submitted as a name/value pair with form data. |
string
|
''
|
|
value
|
The current value of the checkbox, submitted as a name/value pair with form data. |
string
|
- | |
size
|
The checkbox’s size. |
|
'small' | 'medium' | 'large'
|
'medium'
|
disabled
|
Disables the checkbox. |
|
boolean
|
false
|
checked
|
Draws the checkbox in a checked state. |
|
boolean
|
false
|
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
|
defaultChecked
|
The default value of the form control. Primarily used for resetting the form control. |
boolean
|
false
|
|
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
|
''
|
required
|
Makes the checkbox a required field. |
|
boolean
|
false
|
helpText
help-text
|
The checkbox’s help text. If you need to display HTML, use the help-text slot
instead.
|
string
|
''
|
|
validity
|
Gets the validity state object | - | - | |
validationMessage
|
Gets the validation message | - | - | |
updateComplete
|
A read-only promise that resolves when the component has finished updating. |
Learn more about attributes and properties.
Events
| Name | React Event | Description | Event Detail |
|---|---|---|---|
terra-blur
|
onTerraBlur
|
Emitted when the checkbox loses focus. | - |
terra-change
|
onTerraChange
|
Emitted when the checked state changes. | - |
terra-focus
|
onTerraFocus
|
Emitted when the checkbox gains focus. | - |
terra-input
|
onTerraInput
|
Emitted when the checkbox receives input. | - |
terra-invalid
|
onTerraInvalid
|
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.
|
- |
getForm()
|
Gets the associated form, if one exists. | - |
reportValidity()
|
Checks for validity and shows the browser’s 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
|
Learn more about methods.
Custom Properties
| Name | Description | Default |
|---|---|---|
--terra-checkbox-*
|
All checkbox design tokens from horizon.css are supported. |
Learn more about customizing CSS custom properties.
Parts
| Name | Description |
|---|---|
base
|
The component’s base wrapper. |
control
|
The square container that wraps the checkbox’s checked state. |
control--checked
|
Matches the control part when the checkbox is checked. |
control--indeterminate
|
Matches the control part when the checkbox is indeterminate. |
checked-icon
|
The checked icon, an <terra-icon> element. |
indeterminate-icon
|
The indeterminate icon, an <terra-icon> element. |
label
|
The container that wraps the checkbox’s label. |
form-control-help-text
|
The help text’s wrapper. |
Learn more about customizing CSS parts.
Dependencies
This component automatically imports the following dependencies.
-
<terra-icon>