A Text Input is a form element that provides users with a way to read, input, or edit data.

Usage

When to use

• As a form element that provides users with a way to read, input, or edit data in a freeform way.

When not to use

• If needing a multi-line text input, consider Textarea
• If needing to allow the user to make a selection from a predetermined list of options, consider Checkbox, Radio button, or Select.

Types of text inputs

Text Input accepts all native HTML types, but we offer built in styling for the following:

Text

Password

The TextInput component has a visibility toggle feature for password fields. By default, a button appears allowing users to switch easily between visible and obfuscated input.

Search

Loading

Date and time

Required and optional

For complex forms, indicate required fields. This is the most explicit and transparent method and ensures users don’t have to make assumptions. Read more about best practices for marking required fields in forms.

For shorter, simpler forms (e.g., login/signup and feedback requests), indicate optional fields instead.

Readonly, disabled, and hidden fields

Readonly, disabled, and hidden fields are very similar, but there are key differences to be aware of when choosing the correct type of Text Input. Since these fields are not editable by a user, we recommend using them sparingly.

Readonly fields are not editable by the user but the value in the field is passed when the form is submitted.

Disabled fields are not editable by the user and the value in the field is not passed when the form is submitted.

Hidden fields are not visible to the user but the value in the field is passed when the form is submitted.

Character count

For tracking the number of characters entered into a TextInput and defining requirements around minimum and maximum length, refer to the Character count documentation.

Error validation

For error validation recommendations, refer to the Form patterns documentation.

Content

For high-level content recommendations, refer to our Primitives documentation.

How to use this component

There are two ways to use the Text Input component:

• Form::TextInput::Base - the base component: just the <input> control.
• Form::TextInput::Field - the field component: the <input> control, with label, helper text, and error messaging (in a wrapping container).

We recommend using the Field component as it provides built-in accessibility functionality. Use the Base component if needing to achieve custom layouts or for special use cases not covered by the Field component.

Form::TextInput::Field

The basic invocation requires a Label. This creates:

• a <label> element with a for attribute automatically associated with the input ID attribute.
• a <input type="text"> control with an automatically generated ID attribute.

<Hds::Form::TextInput::Field as |F|>
  <F.Label>Cluster name</F.Label>
</Hds::Form::TextInput::Field>

Input value

Pass a @value argument to pre-populate the input.

<Hds::Form::TextInput::Field @value="my-cluster-1234" as |F|>
  <F.Label>Cluster name</F.Label>
</Hds::Form::TextInput::Field>

Type

Pass a @type argument to change the type of input.

<Hds::Form::TextInput::Field @type="email" @value="janedoe@email.com" as |F|>
  <F.Label>Email</F.Label>
</Hds::Form::TextInput::Field>
<br />
<Hds::Form::TextInput::Field @type="date" as |F|>
  <F.Label>Date of birth</F.Label>
</Hds::Form::TextInput::Field>

Helper text

You can add extra information to the field using helper text. When helper text is added, the component automatically adds an aria-describedby attribute to the input control, associating it with the automatically generated ID of the helper text element.

<Hds::Form::TextInput::Field @value="036140285924" as |F|>
  <F.Label>AWS Account ID</F.Label>
  <F.HelperText>Copy this ID to your AWS Resource Access Manager to initiate the resource share.</F.HelperText>
</Hds::Form::TextInput::Field>

Extra content in label and helper text

The Label and HelperText contextual components used in the Field component yield their content. This means you can also pass structured content.

<Hds::Form::TextInput::Field as |F|>
  <F.Label>AWS Account ID <Hds::Badge @size="small" @text="Beta" /></F.Label>
  <F.HelperText>This is an experimental feature (<Hds::Link::Inline @href="#">read more</Hds::Link::Inline>).</F.HelperText>
</Hds::Form::TextInput::Field>

Required vs. optional

Use the @isRequired and @isOptional arguments to add a visual indication that the field is "required" or "optional".

<Hds::Form::TextInput::Field @isRequired={{true}} as |F|>
  <F.Label>AWS Account ID</F.Label>
  <F.HelperText>Copy this ID to your AWS Resource Access Manager to initiate the resource share.</F.HelperText>
</Hds::Form::TextInput::Field>
<br />
<Hds::Form::TextInput::Field @isOptional={{true}} as |F|>
  <F.Label>AWS Account ID</F.Label>
  <F.HelperText>Copy this ID to your AWS Resource Access Manager to initiate the resource share.</F.HelperText>
</Hds::Form::TextInput::Field>

Character count

If the user input needs to be limited to a certain number of characters, use @maxLength on a CharacterCount contextual component to guide the user in meeting the length requirements. This property does not restrict the users from entering characters over the limit. To define the maximum string length that the user can enter, set maxlength attribute on the associated input field.