Examples

Single line field

Multiline field

Guidance

When to use

• If you can’t reasonably predict a user’s answer to a prompt and there might be wide variability in users’ answers.
• When using another type of input will make answering more difficult. For example, birthdays and other known dates are easier to type in than they are to select from a calendar picker.
• When users want to paste in a response.

Guidelines

• Don't use placeholder text in form fields. Use hint text instead, if you need to provide contextual information. Placeholder text disappears after a user types a value, therefore users will no longer have that text available when they need to review their entries. People who have cognitive or visual disabilities have additional problems with placeholder text.
• The length of the text field provides a hint to users as to how much text to write. Do not require users to write paragraphs of text into a single-line input box; use a <textarea> instead.
• Text fields are among the easiest type of input for desktop users but are more difficult for mobile users.
• Only show error messages or styling after a user has interacted with a particular field.
• When using text fields in a form, ensure there's sufficient spacing between fields. Your fields shouldn't feel cramped and users shouldn't confuse which labels and hint text belong to which fields.
  • 8px, --spacer-1, is recommended between form elements including text fields
  • Please reference “spacing” guidelines for additional information.
• View the "Forms" guidelines for additional guidance and best practices.

When to consider alternatives

• When users are choosing from a specific set of options. Consider checkboxes, radio buttons, or a dropdown in these cases.

Accessibility

Accessibility guidance

• Group each set of thematically related controls in a fieldset element. Use the legend element to offer a label within each fieldset. The fieldset and legend elements make it easier for screen reader users to navigate the form.
• Keep your form blocks in a vertical pattern. This approach is ideal, from an accessibility standpoint, because of limited vision that makes it hard to scan from left to right.

Code

React

A TextField component renders an input field as well as supporting UI elements like a label, error message, and hint text.

Review Storybook for React guidance of this component.

Web Component

Go to Storybook for Web Component guidance of this component.

Style customization

The following CSS variables can be overridden to customize Input/Form components:

Form components

This component also makes use of form field styles, which can be customized by the following variables:

Related patterns

• Masked field
• Date field

Learn more

• Form Guidelines
• "Placeholders in Form Fields Are Harmful"

  You are leaving design.cms.gov.

  You're about to connect to a third-party site. Select CONTINUE to proceed or CANCEL to stay on this site.

  Learn more about links to third-party sites.

  ContinueCancel
• Asking for a date of birth

  You are leaving design.cms.gov.

  You're about to connect to a third-party site. Select CONTINUE to proceed or CANCEL to stay on this site.

  Learn more about links to third-party sites.

  ContinueCancel

Component maturity