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

Select

<terra-select> | TerraSelect
Since 1.0 stable

Select fields are a form field used to select one option from a list.

Select

Select fields are a form field used to select one option from a list.

Examples

Basic Select

Astronaut Engineer Scientist 
<terra-select label="Profession">
  <terra-option value="astronaut">Astronaut</terra-option>
  <terra-option value="engineer">Engineer</terra-option>
  <terra-option value="scientist">Scientist</terra-option>
</terra-select>

With Selected Value

Astronaut Engineer Scientist 
<terra-select label="Profession" value="astronaut">
  <terra-option value="astronaut">Astronaut</terra-option>
  <terra-option value="engineer">Engineer</terra-option>
  <terra-option value="scientist">Scientist</terra-option>
</terra-select>

With Placeholder

Astronaut Engineer Scientist 
<terra-select label="Profession" placeholder="Choose a profession">
  <terra-option value="astronaut">Astronaut</terra-option>
  <terra-option value="engineer">Engineer</terra-option>
  <terra-option value="scientist">Scientist</terra-option>
</terra-select>

Required Field

Choose a profession Astronaut Engineer Scientist 
<terra-select label="Profession" required>
  <terra-option value="">Choose a profession</terra-option>
  <terra-option value="astronaut">Astronaut</terra-option>
  <terra-option value="engineer">Engineer</terra-option>
  <terra-option value="scientist">Scientist</terra-option>
</terra-select>

With Help Text

Choose a profession Astronaut Engineer Scientist 
<terra-select
  label="Profession"
  help-text="Select your primary profession or role.">
  <terra-option value="">Choose a profession</terra-option>
  <terra-option value="astronaut">Astronaut</terra-option>
  <terra-option value="engineer">Engineer</terra-option>
  <terra-option value="scientist">Scientist</terra-option>
</terra-select>

Disabled State

Astronaut Engineer Scientist 
<terra-select label="Profession" disabled value="astronaut">
  <terra-option value="astronaut">Astronaut</terra-option>
  <terra-option value="engineer">Engineer</terra-option>
  <terra-option value="scientist">Scientist</terra-option>
</terra-select>

Multiple Selection

Option 1 Option 2 Option 3 Option 4 
<terra-select label="Select Multiple" multiple>
  <terra-option value="option1">Option 1</terra-option>
  <terra-option value="option2" selected>Option 2</terra-option>
  <terra-option value="option3">Option 3</terra-option>
  <terra-option value="option4" selected>Option 4</terra-option>
</terra-select>

With Clear Button

Astronaut Engineer Scientist 
<terra-select label="Profession" clearable value="astronaut">
  <terra-option value="astronaut">Astronaut</terra-option>
  <terra-option value="engineer">Engineer</terra-option>
  <terra-option value="scientist">Scientist</terra-option>
</terra-select>

Sizes

Option 1 Option 2 Option 1 Option 2 Option 1 Option 2 
<terra-select label="Small" size="small" value="option1">
  <terra-option value="option1">Option 1</terra-option>
  <terra-option value="option2">Option 2</terra-option>
</terra-select>

<terra-select label="Medium" size="medium" value="option1" style="margin-top: 1rem;">
  <terra-option value="option1">Option 1</terra-option>
  <terra-option value="option2">Option 2</terra-option>
</terra-select>

<terra-select label="Large" size="large" value="option1" style="margin-top: 1rem;">
  <terra-option value="option1">Option 1</terra-option>
  <terra-option value="option2">Option 2</terra-option>
</terra-select>

With Prefix Icon

Choose a category Articles Features Press Releases 
<terra-select label="Search Category">
  <terra-icon slot="prefix" name="outline-magnifying-glass" library="heroicons"></terra-icon>
  <terra-option value="">Choose a category</terra-option>
  <terra-option value="articles">Articles</terra-option>
  <terra-option value="features">Features</terra-option>
  <terra-option value="press-releases">Press Releases</terra-option>
</terra-select>

Form Integration

Choose a profession Astronaut Engineer Scientist
Submit 
<form id="example-form">
  <terra-select name="profession" label="Profession" required>
    <terra-option value="">Choose a profession</terra-option>
    <terra-option value="astronaut">Astronaut</terra-option>
    <terra-option value="engineer">Engineer</terra-option>
    <terra-option value="scientist">Scientist</terra-option>
  </terra-select>
  <br>
  <terra-button type="submit">Submit</terra-button>
</form>

Usage

Select fields are used in forms to choose one option from a list. Each field should include a clear label that explains what should be selected. Select fields are particularly useful when there are 7 or more options to choose from, as they take up less space than radio buttons.

Best Practices

  • Labels: Always include a clear and concise label for each select field.
  • Placeholder option: Include a default option (e.g., “Choose an option”) as the first option with an empty value to guide users, or use the placeholder attribute.
  • Number of options: For lists with less than 7 options, consider using Radio buttons instead of a Select Field for better usability.
  • Required fields: If only some fields in a form are required, indicate required select fields by adding ”(required)” to the end of the field’s label. If most fields in a form are required, indicate optional fields by adding ”(optional)” to the end of the label.
  • Help text: Use the help-text attribute to provide additional guidance on what should be selected or any constraints.
  • Multiple selection: Use the multiple attribute sparingly, as it can be less intuitive for users. Consider using checkboxes for multiple selections instead.
  • Clear button: Use the clearable attribute when users may need to quickly reset their selection.

Accessibility

  • The terra-select component is built with accessibility in mind, using proper ARIA attributes and keyboard navigation.
  • Labels are properly associated with the select control using aria-labelledby.
  • Required fields are indicated with an asterisk.
  • Help text is provided below the select field for additional context.
  • The component supports keyboard navigation (arrow keys, type-to-select, Enter/Space to select).
  • Focus states are clearly visible with a focus ring.
  • Screen readers are properly notified of value changes.

[component-metadata:terra-select]

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

To import this component using a bundler:

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

To import this component as a React component:

import TerraSelect from '@nasa-terra/components/dist/react/select';

Slots

Name Description
(default) The listbox options. Must be <terra-option> elements.
label The input’s label. Alternatively, you can use the label attribute.
prefix Used to prepend a presentational icon or similar element to the combobox.
suffix Used to append a presentational icon or similar element to the combobox.
clear-icon An icon to use in lieu of the default clear icon.
expand-icon The icon to show when the control is expanded and collapsed. Rotates on open and close.
help-text Text that describes how to use the input. Alternatively, you can use the help-text attribute.

Learn more about using slots.

Properties

Name Description Reflects Type Default
name The name of the select, submitted as a name/value pair with form data. string ''
value The current value of the select, submitted as a name/value pair with form data. When multiple is enabled, the value attribute will be a space-delimited list of values based on the options selected, and the value property will be an array. For this reason, values must not contain spaces. - -
defaultValue
value 		The default value of the form control. Primarily used for resetting the form control. string | string[] ''
size The select’s size. 'small' | 'medium' | 'large' 'medium'
placeholder Placeholder text to show as a hint when the select is empty. string ''
multiple Allows more than one option to be selected. boolean false
maxOptionsVisible
max-options-visible 		The maximum number of selected options to show when multiple is true. After the maximum, ”+n” will be shown to indicate the number of additional items that are selected. Set to 0 to remove the limit. number 3
disabled Disables the select control. boolean false
clearable Adds a clear button when the select is not empty. boolean false
open Indicates whether or not the select is open. You can toggle this attribute to show and hide the menu, or you can use the show() and hide() methods and this attribute will reflect the select’s open state. boolean false
hoist Enable this option to prevent the listbox from being clipped when the component is placed inside a container with overflow: auto|scroll. Hoisting uses a fixed positioning strategy that works in many, but not all, scenarios. boolean false
filled Draws a filled select. boolean false
pill Draws a pill-style select with rounded edges. boolean false
label The select’s label. If you need to display HTML, use the label slot instead. string ''
placement The preferred placement of the select’s menu. Note that the actual placement may vary as needed to keep the listbox inside of the viewport. 'top' | 'bottom' 'bottom'
helpText
help-text 		The select’s help text. If you need to display HTML, use the help-text slot instead. string ''
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 The select’s required attribute. boolean false
getTag A function that customizes the tags to be rendered when multiple=true. The first argument is the option, the second is the current tag’s index. The function should return either a Lit TemplateResult or a string containing trusted HTML of the symbol to render at the specified value. ( option: TerraOption, index: number ) => TemplateResult | string | HTMLElement -
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-change onTerraChange Emitted when the control’s value changes. -
terra-clear onTerraClear Emitted when the control’s value is cleared. -
terra-input onTerraInput Emitted when the control receives input. -
terra-focus onTerraFocus Emitted when the control gains focus. -
terra-blur onTerraBlur Emitted when the control loses focus. -
terra-show onTerraShow Emitted when the select’s menu opens. -
terra-after-show onTerraAfterShow Emitted after the select’s menu opens and all animations are complete. -
terra-hide onTerraHide Emitted when the select’s menu closes. -
terra-after-hide onTerraAfterHide Emitted after the select’s menu closes and all animations are complete. -
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
show() Shows the listbox. -
hide() Hides the listbox. -
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. Pass an empty string to restore validity. message: string
focus() Sets focus on the control. options: FocusOptions
blur() Removes focus from the control. -

Learn more about methods.

Custom Properties

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

Learn more about customizing CSS custom properties.

Parts

Name Description
form-control The form control that wraps the label, input, and help text.
form-control-label The label’s wrapper.
form-control-input The select’s wrapper.
form-control-help-text The help text’s wrapper.
combobox The container the wraps the prefix, suffix, combobox, clear icon, and expand button.
prefix The container that wraps the prefix slot.
suffix The container that wraps the suffix slot.
display-input The element that displays the selected option’s label, an <input> element.
listbox The listbox container where options are slotted.
tags The container that houses option tags when multiple is used.
tag The individual tags that represent each multiselect option.
clear-button The clear button.
expand-icon The container that wraps the expand icon.

Learn more about customizing CSS parts.

Dependencies

This component automatically imports the following dependencies.

  • <terra-icon>
  • <terra-popup>
  • <terra-tag>