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

• Avoid using placeholder text as a substitute for labels. Most browsers render placeholder text with low contrast, making it difficult to read for many users. Instead, use the required label prop to provide a meaningful description of the text field.
• Optionally, use the hint prop to provide additional contextual information or clearer directions for use. Using the label and hint props provides benefits such as reducing cognitive load and increasing the interaction area for users navigating with assistive technology.
• For numeric inputs (e.g., phone numbers, Social Security numbers, credit card numbers), use the mask prop together with the numeric prop. The numeric prop sets inputMode, type, and pattern for better accessibility and consistency, avoiding the pitfalls of type="number". This approach also helps prevent splitting the input into multiple fields, which can result in unclear or inaccessible labeling for screen reader users.

Accessibility testing

For mobile devices, text fields should work in both portrait and landscape orientation with no loss of functionality.

Keyboard navigation

• Users must be able to use only a keyboard to navigate to the text field, type in it, and navigate away from it.
• Focus indicators must be clearly visible around the text fields.

Screen reader

• Screen readers must announce text fields and their labels in the same order they appear visually on the page.
• Screen readers must announce the purpose of each text field (e.g., “Edit, blank. Type in text.”).
• Screen readers must announce associated labels and instructions when a text field receives focus (e.g., “Enter first name.”).
• Screen readers must announce any text provided to the ariaLabel prop.

Zoom magnification

• When zoomed to 200%, text fields must remain legible, functional, and properly sized.

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:

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