TextField allows for multiple types of text input.

Props

Component props
Name
Type
Default
id
Required
string
-

A unique identifier for the input.

onChange
Required
({| event: SyntheticInputEvent<HTMLInputElement>, value: string, |}) => void
-

Callback triggered when the value of the input changes.

autoComplete
"current-password" | "new-password" | "on" | "off" | "username" | "email"
-

Indicate if autocomplete should be available on the input, and the type of autocomplete.

disabled
boolean
false

Indicate if the input is disabled.

errorMessage
React.Node
-

For most use cases, pass a string with a helpful error message (be sure to localize!). In certain instances it can be useful to make some text clickable; to support this, you may instead pass a React.Node to wrap text in Link or TapArea.

hasError
boolean
false

This field is deprecated and will be removed soon. Please do not use.

helperText
string
-

More information about how to complete the form field.

label
string
-

The label for the input. Be sure to localize the text.

name
string
-

A unique name for the input.

onBlur
({| event: SyntheticFocusEvent<HTMLInputElement>, value: string, |}) => void
-

Callback triggered when the user blurs the input.

onFocus
({| event: SyntheticFocusEvent<HTMLInputElement>, value: string, |}) => void
-

Callback triggered when the user focuses the input.

onKeyDown
({| event: SyntheticKeyboardEvent<HTMLInputElement>, value: string, |}) => void
-

Callback triggered when the user presses any key while the input is focused.

placeholder
string
-

Placeholder text shown the the user has not yet input a value.

size
"md" | "lg"
"md"

md: 40px, lg: 48px

tags
$ReadOnlyArray<React.Element<typeof Tag>>
-

List of tags to display in the component.

type
"date" | "email" | "number" | "password" | "tel" | "text" | "url"
"text"

The type of input. For non-telephone numerical input, please use NumberField.

value
string
-

The current value of the input.

Usage guidelines

When to Use
  • Any time succinct data needs to be entered by a user, like a date, email address, name, or Pin title.
When Not to Use
  • Situations where long amounts of text need to be entered, since the full content of the TextField will be truncated. Use TextArea instead.

Best practices

Do

Use helper text for important information. Helper text helps users understand how to complete the text field or to indicate any needed input.

Don't

Put essential information in the placeholder text, since it disappears when the user types. The placeholder text is not a replacement for the label.

Do

Always ensure the text field has a visible label. The label provides context and supports users when filling in information.

Don't

Remove the label, as this creates accessibility and usability issues.

Do

Only place related fields on the same line.

Don't

Place unrelated text fields on the same line, as this can create comprehension issues.

Do

Provide clear and useful error messages that help the user fix the issue. Error messages should be displayed in a timely manner — typically once the field loses focus or when the form is submitted.

Don't

Display generic error messages, such as "There is an error".

Do

Consider all text fields as required, unless explicitly noted as optional.

Don't

Mark fields as required.

Accessibility

Comprehension

Be sure to provide instructions to help users understand how to complete the form and use individual form controls.

Labels

Ensure the labels are precise and concise. Labels should only describe the text field they are associated with, and they must be visible.

Validation

When providing a validation message, make sure the instructions are clear and help users complete the field. For example, "Passwords must contain at least 20 characters". In addition, use the helper text to provide instructions to help users understand how to complete the text field or to indicate any needed input, allowed formats, timing limitations, or other pertinent information.
These practices give screen readers and users of assistive technologies more information about the form, helping them to fill it out.

Keyboard navigation

TextField has conventional keyboard support.

  • Users relying on the keyboard expect to move focus to each TextField by using the tab key or shift+tab when moving backwards
  • If type is set to "number" (or if using NumberField), users can press the up and down arrow keys to adjust the field value
  • Setting disabled will prevent TextField from receiving keyboard focus or input

Autofocus

TextField intentionally lacks support for autofocus. Generally speaking,
autofocus interrupts normal page flow for screen readers making it an
anti-pattern for accessibility.

onSubmit

TextField is commonly used as an input in forms alongside submit buttons.
In these cases, users expect that pressing Enter or Return with the input
focused will submit the form.

Out of the box, TextField doesn't expose an onSubmit handler or
individual key event handlers due to the complexities of handling these
properly. Instead, developers are encouraged to wrap TextField
in a <form> and attach an onSubmit handler to that <form>.

Localization

Be sure to localize errorMessage, helperText, label, and placeholder.

Variants

Disabled

Disabled TextFields cannot be interacted with using the mouse or keyboard.

Helper text

Whenever you want to provide more information about a form field, you should use helperText.

Error message

TextField can display an error message.
Simply pass in an errorMessage when there is an error present and we will handle the rest.
Be sure to localize the text!

Tags

You can include Tag elements in the input using the tags prop.

Note that TextField does not internally manage tags. Tag management should be handled in the application state through the component's event callbacks. We recommend creating new tags on enter key presses, and removing them on backspaces when the cursor is in the beginning of the field. We also recommend filtering out empty tags.

This example showcases the recommended behavior. In addition, it creates new tags by splitting the input on spaces, commas, and semicolons.

Refs

TextField can accept a ref for anchoring Popover-based components.

TextArea
When users need to enter long amounts of text, use TextArea to ensure the full content will be shown.

NumberField
For numerical input, use NumberField. (For telephone numbers, use <TextField type="tel" />.)

SearchField
If the input is used for searching content, use SearchField.