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

Input

<terra-input> | TerraInput
Since 1.0 stable

A text input component with consistent styling across the design system.

<terra-input placeholder="Enter text..."></terra-input>

import TerraInput from '@nasa-terra/components/dist/react/input';

const App = () => <TerraInput placeholder="Enter text..." />;

Usage

The Input component provides a standardized text input field with support for labels, help text, and various input types.

Text fields are used in forms to capture short strings of text. Each field should include a clear label that explains what should be entered. If only some fields in a form are required, indicate required fields by adding ”(required)” to the end of the field’s label, or use the required prop which will show an asterisk.

The component supports help text, which can be used to provide guidance on what type of text is expected, character count limits, accepted characters, etc. 

<terra-input
  label="Email Address"
  type="email"
  placeholder="you@example.com"
  help-text="We'll never share your email."
></terra-input>

Properties

Property Type Default Description
type 'text' | 'email' | 'number' | 'password' | 'search' | 'tel' | 'url' 'text' The type of input
name string '' The name of the input, submitted with form data
value string '' The current value of the input
placeholder string '' Placeholder text to show when the input is empty
disabled boolean false Disables the input
readonly boolean false Makes the input read-only
required boolean false Makes the input required (shows asterisk in label)
autocomplete string - HTML autocomplete attribute
minlength number - Minimum length of text
maxlength number - Maximum length of text
min number | string - Minimum value (for number inputs)
max number | string - Maximum value (for number inputs)
step number | 'any' - Step value (for number inputs)
pattern string - Regex pattern for validation
inputMode 'none' | 'text' | 'decimal' | 'numeric' | 'tel' | 'search' | 'email' | 'url' - Virtual keyboard hint for mobile devices
label string '' Label text displayed above the input
hideLabel boolean false Visually hides the label (still accessible to screen readers)
helpText string '' Help text displayed below the input
resettable boolean false Shows a reset icon in the suffix that clears the input value
defaultValue string '' The default value used when resetting the input

Events

Event Description
terra-input Emitted when the input receives input (fires on every keystroke)
terra-change Emitted when the input value changes and focus is lost
terra-focus Emitted when the input gains focus
terra-blur Emitted when the input loses focus

Slots

Slot Description
prefix Content to prepend before the input (typically an icon)
suffix Content to append after the input (typically an icon)

Examples

Basic Input 

<terra-input label="Username" placeholder="Enter username"></terra-input>

With Help Text 

<terra-input
  label="Password"
  type="password"
  help-text="Must be at least 8 characters"
></terra-input>

Required Field 

<terra-input
  label="Full Name"
  required
  placeholder="John Doe"
></terra-input>

Disabled State 

<terra-input
  label="Disabled Input"
  value="Cannot edit this"
  disabled
></terra-input>

Read-only State 

<terra-input
  label="Read-only Input"
  value="This is read-only"
  readonly
></terra-input>

With Prefix Icon 

<terra-input label="Email" type="email" placeholder="you@example.com">
  <svg slot="prefix" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
    <path d="M4 4h16c1.1 0 2 .9 2 2v12c0 1.1-.9 2-2 2H4c-1.1 0-2-.9-2-2V6c0-1.1.9-2 2-2z"></path>
    <polyline points="22,6 12,13 2,6"></polyline>
  </svg>
</terra-input>

With Suffix Icon 

<terra-input label="Search" type="search" placeholder="Search...">
  <svg slot="suffix" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
    <circle cx="11" cy="11" r="8"></circle>
    <path d="m21 21-4.35-4.35"></path>
  </svg>
</terra-input>

Resettable Input

When resettable is true, a clear icon appears in the suffix when the input has a value. Clicking the icon resets the input to its defaultValue (or empty string if no defaultValue is set). The reset icon only appears when the value differs from the default value. 



<terra-input
  label="Name"
  type="text"
  resettable
  value="John Smith"
></terra-input><br /><br />

<terra-input
  label="Search"
  type="search"
  placeholder="Search..."
  resettable
  value=""
></terra-input>

Number Input 

<terra-input
  label="Age"
  type="number"
  min="0"
  max="120"
  step="1"
  placeholder="Enter age"
></terra-input>

Phone Number 

<terra-input
  label="Phone"
  type="tel"
  pattern="[0-9]{3}-[0-9]{3}-[0-9]{4}"
  placeholder="555-123-4567"
  help-text="Format: 555-123-4567"
></terra-input>

Hidden Label 

<terra-input
  label="Search"
  hide-label
  type="search"
  placeholder="Search..."
>
  <svg slot="prefix" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
    <circle cx="11" cy="11" r="8"></circle>
    <path d="m21 21-4.35-4.35"></path>
  </svg>
</terra-input>

Methods

Method Description
focus(options?: FocusOptions): void Sets focus on the input
blur(): void Removes focus from the input
select(): void Selects all text in the input
setSelectionRange(start: number, end: number, direction?: string): void Sets the text selection range

Best Practices

  1. Always provide a label for accessibility - use hide-label if you need to hide it visually
  2. Use help-text to provide additional context or validation requirements
  3. Use appropriate input type for better mobile keyboard support
  4. Add required prop for mandatory fields (shows asterisk indicator)
  5. Use placeholder as a hint, not as a replacement for labels
  6. Consider using prefix/suffix slots for icons to improve visual hierarchy
  7. For compact fields (e.g., single email field), you can use hide-label and place the label text in the placeholder
  8. If only some fields in a form are required, indicate required fields. If most fields are required, indicate optional fields with ”(optional)” in the label

Accessibility

  • Label is automatically associated with the input via for attribute
  • Required fields show a visual indicator (asterisk) and have the required attribute
  • Help text is associated with the input for screen readers
  • Disabled state is properly conveyed to assistive technologies
  • Hidden labels remain accessible to screen readers

[component-metadata:terra-input]

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

To import this component using a bundler:

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

To import this component as a React component:

import TerraInput from '@nasa-terra/components/dist/react/input';

Slots

Name Description
prefix Used to prepend content (like an icon) to the input.
suffix Used to append content (like an icon) to the input. When clearable or resettable is true, this slot is overridden.
clear-icon An icon to use in lieu of the default clear icon.
show-password-icon An icon to use in lieu of the default show password icon.
hide-password-icon An icon to use in lieu of the default hide password icon.
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
defaultValue The default value of the form control. Primarily used for resetting the form control. string ''
resettable When true, shows a reset icon in the suffix that clears the input value when clicked. The input will be reset to its defaultValue (or empty string if no defaultValue is set). 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 ''
validity Gets the validity state object - -
validationMessage Gets the validation message - -
valueAsDate Gets or sets the current value as a Date object. Returns null if the value can’t be converted. This will use the native <input type="{{type}}"> implementation and may result in an error. - -
valueAsNumber Gets or sets the current value as a number. Returns NaN if the value can’t be converted. - -
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-input onTerraInput Emitted when the input receives input. -
terra-change onTerraChange Emitted when an alteration to the control’s value is committed by the user. -
terra-focus onTerraFocus Emitted when the control gains focus. -
terra-blur onTerraBlur Emitted when the control loses focus. -
terra-invalid onTerraInvalid Emitted when the form control has been checked for validity and its constraints aren’t satisfied. -
terra-clear onTerraClear Emitted when the clear button is activated. -

Learn more about events.

Methods

Name Description Arguments
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
setRangeText() Replaces a range of text with a new string. replacement: string , start: number , end: number , selectMode: 'select' | 'start' | 'end' | 'preserve'
showPicker() Displays the browser picker for an input element (only works if the browser supports it for the input type). -
stepUp() Increments the value of a numeric input type by the value of the step attribute. -
stepDown() Decrements the value of a numeric input type by the value of the step attribute. -

Learn more about methods.

Parts

Name Description
base The component’s base wrapper.
input The internal input control.
prefix The container for prefix content.
suffix The container for suffix content.
clear-button The clear button.
password-toggle-button The password toggle button.
form-control-help-text The help text’s wrapper.
form-control-error-text The error text’s wrapper.

Learn more about customizing CSS parts.

Dependencies

This component automatically imports the following dependencies.

  • <terra-icon>