About Project Overview Contributing Getting Started Installation Usage Themes Customizing Frameworks React Vue Angular GitHub Light Dark System

Option

<terra-option> | TerraOption
Since 1.0 stable

Options define the selectable items within various form controls such as select.

Option

Options define the selectable items within various form controls such as terra-select.

Examples

Basic Option

Option 1 Option 2 Option 3 
<terra-select label="Choose an option">
  <terra-option value="option1">Option 1</terra-option>
  <terra-option value="option2">Option 2</terra-option>
  <terra-option value="option3">Option 3</terra-option>
</terra-select>

Selected Option

Option 1 Option 2 (Selected) Option 3 
<terra-select label="Choose an option">
  <terra-option value="option1">Option 1</terra-option>
  <terra-option value="option2" selected>Option 2 (Selected)</terra-option>
  <terra-option value="option3">Option 3</terra-option>
</terra-select>

Disabled Option

Option 1 Option 2 (Disabled) Option 3 
<terra-select label="Choose an option">
  <terra-option value="option1">Option 1</terra-option>
  <terra-option value="option2" disabled>Option 2 (Disabled)</terra-option>
  <terra-option value="option3">Option 3</terra-option>
</terra-select>

With Prefix and Suffix Icons

Option 1 Option 2 
<terra-select label="Choose an option">
  <terra-option value="option1">
    <terra-icon slot="prefix" name="outline-check" library="heroicons"></terra-icon>
    Option 1
    <terra-icon slot="suffix" name="outline-arrow-right" library="heroicons"></terra-icon>
  </terra-option>
  <terra-option value="option2">
    <terra-icon slot="prefix" name="outline-star" library="heroicons"></terra-icon>
    Option 2
  </terra-option>
</terra-select>

Usage

Options are used within terra-select components to define the available choices. Each option must have a unique value attribute and can include text content or slotted content for more complex labels.

Best Practices

  • Unique values: Each option must have a unique value attribute. Values cannot contain spaces.
  • Clear labels: Use clear, descriptive text for option labels that help users understand their choices.
  • Disabled options: Use the disabled attribute to prevent selection of options that are currently unavailable, rather than hiding them.
  • Selected state: Use the selected attribute to set the default selected option, or let the terra-select component manage selection via its value property.

Accessibility

  • Options automatically receive proper ARIA attributes (role="option", aria-selected, aria-disabled).
  • Keyboard navigation is fully supported (arrow keys to navigate, Enter/Space to select).
  • Screen readers are properly notified of option states and selections.
  • Disabled options are clearly indicated to assistive technologies.

[component-metadata:terra-option]

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.

Script Import Bundler React

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/option/option.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/option/option.js';

To import this component using a bundler:

import '@nasa-terra/components/dist/components/option/option.js';

To import this component as a React component:

import TerraOption from '@nasa-terra/components/dist/react/option';

Slots

Name Description
(default) The option’s label.
prefix Used to prepend an icon or similar element to the menu item.
suffix Used to append an icon or similar element to the menu item.

Learn more about using slots.

Properties

Name Description Reflects Type Default
value The option’s value. When selected, the containing form control will receive this value. The value must be unique from other options in the same group. Values may not contain spaces, as spaces are used as delimiters when listing multiple values. string ''
disabled Draws the option in a disabled state, preventing selection. boolean false
updateComplete A read-only promise that resolves when the component has finished updating.

Learn more about attributes and properties.

Methods

Name Description Arguments
getTextLabel() Returns a plain text label based on the option’s content. -

Learn more about methods.

Custom Properties

Name Description Default
--terra-option-* All option design tokens from horizon.css are supported.

Learn more about customizing CSS custom properties.

Parts

Name Description
checked-icon The checked icon, an <terra-icon> element.
base The component’s base wrapper.
label The option’s label.
prefix The container that wraps the prefix.
suffix The container that wraps the suffix.

Learn more about customizing CSS parts.

Dependencies

This component automatically imports the following dependencies.

  • <terra-icon>