Text Input

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

Types of text inputs

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

Text

Password

Search

Date and time

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, use Textarea
• If needing to allow the user to make a selection from a predetermined list of options, use Checkbox, Radio button, or Select.

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 (ie. login/signup and feedback requests), indicate optional fields instead.

Readonly, disabled, and hidden fields

Readonly and disabled fields are similar in that the value is not editable by the user. Where they differ is in what happens to the data upon form submission. Data in readonly fields gets passed when the form is submitted, while data in disabled fields does not.

We recommend using a hidden field, if the data needs to be submitted but not reviewed by the user first.

Use these fields sparingly.

Validation

Types of validation

Use a combination of client side and server side validation for the best user experience. Catching basic errors with client side validation allows the user to quickly resolve the error before submitting the form.

Client side validation

Client side validation, sometimes also referred to as inline validation, is an initial check that happens in the browser to ensure required fields are filled out and that the value is in the correct format. Learn more about client side validation.

Server side validation

Server side validation provides a more thorough check on the server once the data has been submitted and helps keep our applications safe.

When using server side validation, display an AlertInline in the Critical variant above the form listing all errors with links to each invalid field.

Displaying multiple error messages

We recommend showing all applicable error messages directly under their corresponding form field.

Content

Form::Label

• We recommend keeping labels clear and concise, about 1-3 words. They should not consist of full sentences.
• 3.3.2 Labels or Instructions (A): Labels or instructions are provided when content requires user input.

Form::HelperText

• Use Form::HelperText when needing to provide the user with extra details about the data you’re asking them to input, eg. formatting requirements such as MM-DD-YYYY.

Form::Error

• Error messages need to provide the user with enough context to guide them in resolving the error.
• Keep messages short and to the point.
• eg. "Enter a valid email address.", "Resource Share ARN starts with arn-"
• Avoid overt politeness; don’t use "please" or "thank you" in your messaging.
• 3.3.1 Error Identification (A): If an input error is automatically detected, the item that is in error is identified and the error is described to the user in text.
• 3.3.3 Error Suggestion (AA): If an input error is automatically detected and suggestions for correction are known, then the suggestions are provided to the user, unless it would jeopardize the security or purpose of the content.
• 3.3.4 Error Prevention (Legal, Financial, Data) (AA): For web pages that cause legal commitments or financial transactions for the user to occur, that modify or delete user-controllable data in data storage systems, or that submit user test responses, at least one of the following is true: submissions are reversible, data is checked and user is provided an opportunity to correct them, a mechanism is available for reviewing, confirming and correcting the information before finalizing the submission.
• 4.1.3 Status Messages(AA): In content implemented using markup language, status messages can be programmatically determined through role or properties such that they can be presented to the user by assistive technologies without receiving focus.

Refer to HashiCorp’s Style, Language, and Voice Guidelines (internal only) for more content tips.

Related

• Select
• Textarea

How to use this component

There are two ways to use the Form::TextInput component: using the "base" variant (essentially just the control itself) or using the "field" variant (the control plus label, helper text and error). We recommend using "field" because it provides built-in accessibility functionality. Use "base" if needing to achieve custom layouts or have special use cases not covered by the "field" variant.

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. For the list of supported types, see Component API.

<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" 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 / 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>

Validation

To indicate a field is invalid, declare that it’s invalid by using the @isInvalid argument and provide an error message using the Error contextual component.

<Hds::Form::TextInput::Field @type="email" @value="jane.doe@.com" @isInvalid={{true}} as |F|>
  <F.Label>Email</F.Label>
  <F.Error>The provided email is not valid.</F.Error>
</Hds::Form::TextInput::Field>

Add more than one error message using the more specific Message contextual component.

<Hds::Form::TextInput::Field @type="password" @value="1234" @isInvalid={{true}} as |F|>
  <F.Label>Password</F.Label>
  <F.Error as |E|>
    <E.Message>Length should be at least 12 characters</E.Message>
    <E.Message>Must contain at least a special character</E.Message>
  </F.Error>
</Hds::Form::TextInput::Field>

Custom control ID

If it’s necessary to have custom ID for the control, instead of the one automatically generated by the component (i.e., because it needs to be referenced in the code for other reasons), pass the @id argument to the field.

<Hds::Form::TextInput::Field @id="my-control" 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>

Additional aria-describedby

Pass an @extraAriaDescribedBy argument to the field to connect one or more extra elements describing the field to the control. This provides extra ID values to the aria-describedby attribute of the control, in addition to those automatically generated by the component.

<Hds::Form::TextInput::Field @extraAriaDescribedBy="my-extra-element-ID" 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>

HTML native attributes

...attributes spreading is supported in the field. This means you can use all the standard HTML attributes of the <input> element. This can be useful in case you want to add specific native behaviors to the field, that are not exposed directly by the component (eg. providing a name for the control, or adding min max minlength maxlength pattern attributes to it).

<Hds::Form::TextInput::Field @type="password" name="user-password" placeholder="Insert your password here" minlength="4" maxlength="64" as |F|>
  <F.Label>Password</F.Label>
</Hds::Form::TextInput::Field>

Events handling

Thanks to the ...attributes spreading over the <input> element, you can use all the usual Ember techniques for event handling, validation, etc. You can use different events, depending on your context (eg. input, blur, change).

<Hds::Form::TextInput::Field @type="email" placeholder="eg. name.surname@email.com" {{on "blur" this.yourOnBlurFunction}} as |F|>
  <F.Label>Email</F.Label>
</Hds::Form::TextInput::Field>

Custom width

By default the input control width is set to fill the parent container, with the exception of "date" and "time" input types.

Pass a custom width for the control using the @width argument.

<Hds::Form::TextInput::Field @type="search" placeholder="Search clusters" @width="200px" as |F|>
  <F.Label>Filter the list:</F.Label>
</Hds::Form::TextInput::Field>

Form::TextInput::Base

The "base" element is intended for rare cases where the "field" variant can’t be used and a custom implementation is needed. Most of the details for the "field" variant also apply to the "base" variant, but see the Component API for more details.

A basic invocation requires a @type argument to be passed.

This creates:

• a <input type="text"> control with an automatically generated ID attribute

<Hds::Form::TextInput::Base
  @type="email"
  @value="janedoe@email.com"
  aria-label="User email"
  placeholder="eg. name.surname@email.com"
  @isRequired={{true}}
  {{on "blur" this.yourOnBlurFunction}}
/>

Component API

The Form::TextInput component has two different variants, with their own APIs:

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

Form::TextInput::Base

Form::TextInput::Field

Contextual components

Label, helper text, and error content are passed to the field as yielded components, using the Label, HelperText, Error keys.

Anatomy

States

Conformance rating

Form::TextInput::Field

Form::TextInput::Field is conformant when used as directed. For this reason, we recommend using Form::TextInput::Field by default.

Form::TextInput::Base

Form::TextInput::Base is not conformant until it has an accessible name.

Applicable WCAG Success Criteria

This section is for reference only, some descriptions have been truncated for brevity.

This component intends to conform to the following WCAG Success Criteria:

Support

If any accessibility issues have been found within this component, please let us know by submitting an issue.