TextField

The TextField component provides a customizable text field that can be used to collect user information, such as name, email, password, or other types of data. It is a wrapper around the native <input /> element, and includes an optional label and validation alert. The label and input are automatically associated for screen readers.

Usage Guidelines

Basic Usage

Use the TextField to collect user information such as name, email, password, or other types of data, using labels, descriptions, and validation messages for additional context.

<TextField description="Enter your full name" isRequired label="Name" />

Prefix

Use the prefix prop to add a prefix to the input. The prefix can be used to provide additional context.

<TextField
  description="Enter your full name"
  isRequired
  label="Name"
  prefix="👋"
/>

States

Disabled

The disabled state of the text field is used to indicate that the user cannot interact with the field.

<TextField
  description="Enter your full name"
  isDisabled
  label="Name"
  value="Linda Belcher"
/>

Read-only

The read-only state of the text field is used to make the text field non-editable.

<TextField
  description="Enter your full name"
  isReadOnly
  isRequired
  label="Name"
  value="Linda Belcher"
  validationMessage="What a great name!"
  validationState="success"
/>

Validation

Error

In the case of an error when validating a field, the validationState prop should be set to error and the validationMessage prop should be set to the error message.

<TextField
  description="Enter your full name"
  isRequired
  label="Name"
  validationMessage="This field is required"
  validationState="error"
/>

Success

In the case of success when validating a field, the validationState prop should be set to success and the validationMessage prop should be set to the success message.

<TextField
  description="Enter your full name"
  isRequired
  label="Name"
  validationMessage="That's a great name!"
  validationState="success"
  value="Linda Belcher"
/>

Warning
In the case of a warning when validating a field, the validationState prop should be set to warning and the validationMessage prop should be set to the warning message.

<TextField
  description="Enter your full name"
  isRequired
  label="Name"
  validationMessage="Consider changing your name to your real name"
  validationState="warning"
  value="This is obviously not my name"
/>

Props

interface TextFieldProps

align ? "left" | "right" | null

Change the alignment of the input text.

label ? string

The label for the input.

description ? string

Shows a description under the label.

isDisabled ? boolean

Controls if the textfield is disabled.

placeholder ? string

Shows a placeholder in the input.

prefix ? AddonProps

Render the input with a prefix.

validationMessage ? string

Shows a validation message under the input.

validationState ? "error" | "success" | "warning"

Changes the appearance of the text field.

validationBehavior ? "native" | "aria"

Whether to use native HTML form validation to prevent form submission when the value is missing or invalid, or mark the field as required or invalid via ARIA.

Defaults to 'native'

enterKeyHint ? "enter" | "done" | "go" | "next" | "previous" | "search" | "send"

An enumerated attribute that defines what action label or icon to preset for the enter key on virtual keyboards. See MDN.

isReadOnly ? boolean

Whether the input can be selected but not changed by the user.

isRequired ? boolean

Whether user input is required on the input before form submission.

validate ? (value: string) => true | ValidationError | null

A function that returns an error message if a given value is invalid. Validation errors are displayed to the user when the form is submitted if validationBehavior="native". For realtime validation, use the isInvalid prop instead.

autoFocus ? boolean

Whether the element should receive focus on render.

onFocus ? (e: FocusEvent) => void

Handler that is called when the element receives focus.

onBlur ? (e: FocusEvent) => void

Handler that is called when the element loses focus.

onFocusChange ? (isFocused: boolean) => void

Handler that is called when the element's focus status changes.

onKeyDown ? (e: KeyboardEvent) => void

Handler that is called when a key is pressed.

onKeyUp ? (e: KeyboardEvent) => void

Handler that is called when a key is released.

value ? string

The current value (controlled).

defaultValue ? string

The default value (uncontrolled).

onChange ? (value: string) => void

Handler that is called when the value changes.

excludeFromTabOrder ? boolean

Whether to exclude the element from the sequential tab order. If true, the element will not be focusable via the keyboard by tabbing. This should be avoided except in rare scenarios where an alternative means of accessing the element or its functionality via the keyboard is available.

id ? string

The element's unique identifier. See MDN.

autoComplete ? string

Describes the type of autocomplete functionality the input should provide if any. See MDN.

maxLength ? number

The maximum number of characters supported by the input. See MDN.

minLength ? number

The minimum number of characters required by the input. See MDN.

pattern ? string

Regex pattern that the value of the input must match to be valid. See MDN.

type ? "search" | "text" | "url" | "tel" | "email" | "password" | (string & {})

The type of input to render. See MDN.

Defaults to 'text'

inputMode ? "none" | "search" | "text" | "url" | "tel" | "email" | "numeric" | "decimal"

Hints at the type of data that might be entered by the user while editing the element or its contents. See MDN.

autoCorrect ? string

An attribute that takes as its value a space-separated string that describes what, if any, type of autocomplete functionality the input should provide. See MDN.

spellCheck ? string

An enumerated attribute that defines whether the element may be checked for spelling errors. See MDN.

name ? string

The name of the input element, used when submitting an HTML form. See MDN.

form ? string

The <form> element to associate the input with. The value of this attribute must be the id of a <form> in the same document. See MDN.

onCopy ? ClipboardEventHandler

Handler that is called when the user copies text. See MDN.

onCut ? ClipboardEventHandler

Handler that is called when the user cuts text. See MDN.

onPaste ? ClipboardEventHandler

Handler that is called when the user pastes text. See MDN.

onCompositionStart ? CompositionEventHandler

Handler that is called when a text composition system starts a new text composition session. See MDN.

onCompositionEnd ? CompositionEventHandler

Handler that is called when a text composition system completes or cancels the current text composition session. See MDN.

onCompositionUpdate ? CompositionEventHandler

Handler that is called when a new character is received in the current text composition session. See MDN.

onSelect ? ReactEventHandler

Handler that is called when text in the input is selected. See MDN.

onBeforeInput ? FormEventHandler

Handler that is called when the input value is about to be modified. See MDN.

onInput ? FormEventHandler

Handler that is called when the input value is modified. See MDN.

style ? StyleOrFunction

The inline style for the element. A function may be provided to compute the style based on component state.

className ? ClassNameOrFunction

The CSS className for the element. A function may be provided to compute the class based on component state.

children ? ChildrenOrFunction

The children of the component. A function may be provided to alter the children based on component state.

slot ? string | null

A slot name for the component. Slots allow the component to receive props from a parent component. An explicit null value indicates that the local props completely override all props received from a parent.