Text field
Material 3 filled, outlined, secure, and multiline text fields with labels, validation, browser form behavior, and accessible input semantics.
Text fields let users enter and edit text. Material 3 defines the filled and outlined visual families; m3-ui layers that presentation over native input/textarea behavior and React Aria field semantics.
import { TextField } from '@m3-ui/ui';
<TextField
label="Email"
name="email"
type="email"
autoComplete="email"
isMultiline={false}
/>When to use
Use text fields for free-form text or structured values that benefit from direct keyboard entry. Choose filled or outlined presentation consistently within a form hierarchy instead of mixing variants arbitrarily.
Use picker/selection components when constrained choices are clearer than typing. Use SecureTextField only when masking/revealing a single-line value is appropriate; it is part of the text-field family, not a separate Material component family.
Variants
| Public component | Material/web role |
|---|---|
TextField | Filled text field |
OutlinedTextField | Outlined text field |
SecureTextField | Filled single-line secure field |
OutlinedSecureTextField | Outlined single-line secure field |
TextField can also render multiline input through its public multiline/rows contract. Native browser attributes such as type, name, autoComplete, input mode, and refs remain available where applicable.
Labels and supporting content
A visible label gives the field a stable identity. supportingText (or the documented description alias) adds guidance without replacing the label.
Prefix, suffix, leading-icon, and trailing-icon slots belong to the Material field composition. Do not use decorative slots as a substitute for a clear label.
Validation and errors
Validation state is semantic, not only visual. Drive isInvalid and errorMessage from native constraints or application validation state.
The component renders the Material error treatment and exposes the field/error relationship; it does not invent business validation rules. Cross-field, server, and workflow validation remain application-owned.
Secure text fields
SecureTextField and OutlinedSecureTextField use the same field composition but always render a single-line native input. They default to password presentation and can expose a reveal action.
<SecureTextField
label="Password"
name="password"
autoComplete="current-password"
/>Reveal state can be uncontrolled with defaultRevealed or controlled with isRevealed and onRevealChange. The reveal button uses pressed/toggle semantics and preserves input focus/selection where browser APIs allow.
Reveal changes presentation only. It does not store credentials, encrypt the value, choose password-strength rules, implement a password manager, or define an application's security policy.
Behavior and states
React Aria owns field, label, description, error, input/textarea relationships and interaction behavior. The browser owns editing, selection, autocomplete, form participation, and native input capabilities. Material tokens own container, indicator/outline, typography, icon slots, state layers, and error presentation.
Disabled and read-only are different states: disabled controls are unavailable, while read-only values remain readable without permitting edits. Use the state that matches the actual workflow rather than a visual preference.
Accessibility
Keep labels meaningful and expose errors as text. Use native attributes for browser-specific input requirements. Do not rely on placeholder text as the only label.
For secure fields, localize reveal/hide action labels when needed and keep them action-oriented. The reveal icon is not the accessible name; the toggle button's label and pressed state communicate the control.
API reference
TextField
TextField(props: TextFieldProps): JSX.ElementProps
| Name | Type | Default | Description | Origin |
|---|---|---|---|---|
description | ReactNode | — | — | @m3-ui/ui |
errorMessage | ChildrenOrFunction<FieldErrorRenderProps> | — | — | @m3-ui/ui |
inputProps | Omit<InputProps & RefAttributes<HTMLInputElement>, "className"> | undefined | — | Props forwarded to the native input when `isMultiline` is false. | @m3-ui/ui |
inputRef | Ref<HTMLInputElement> | undefined | — | Ref to the native input when `isMultiline` is false. | @m3-ui/ui |
isMultiline | boolean | undefined | — | — | @m3-ui/ui |
label | ReactNode | — | — | @m3-ui/ui |
leadingIcon | ReactNode | — | — | @m3-ui/ui |
placeholder | string | undefined | — | — | @m3-ui/ui |
prefix | ReactNode | — | — | @m3-ui/ui |
rows | number | undefined | — | — | @m3-ui/ui |
suffix | ReactNode | — | — | @m3-ui/ui |
supportingText | ReactNode | — | — | @m3-ui/ui |
trailingIcon | ReactNode | — | — | @m3-ui/ui |
Inherited React / web props (119)
| Name | Type | Default | Description | Origin |
|---|---|---|---|---|
aria-activedescendant | string | undefined | — | Identifies the currently active element when DOM focus is on a composite widget, textbox, group, or application. | react-aria |
aria-autocomplete | "none" | "list" | "inline" | "both" | undefined | — | Indicates whether inputting text could trigger display of one or more predictions of the user's intended value for an input and specifies how predictions would be presented if they are made. | react-aria |
aria-controls | string | undefined | — | Identifies the element (or elements) whose contents or presence are controlled by the current element. | react-aria |
aria-describedby | string | undefined | — | Identifies the element (or elements) that describes the object. | @react-types/shared |
aria-details | string | undefined | — | Identifies the element (or elements) that provide a detailed, extended description for the object. | @react-types/shared |
aria-errormessage | string | undefined | — | Identifies the element that provides an error message for the object. | @react-types/shared |
aria-haspopup | boolean | "true" | "false" | "dialog" | "grid" | "listbox" | "menu" | "tree" | undefined | — | Indicates the availability and type of interactive popup element, such as menu or dialog, that can be triggered by an element. | react-aria |
aria-label | string | undefined | — | Defines a string value that labels the current element. | @react-types/shared |
aria-labelledby | string | undefined | — | Identifies the element (or elements) that labels the current element. | @react-types/shared |
autoComplete | string | undefined | — | Describes the type of autocomplete functionality the input should provide if any. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefautocomplete). | @react-types/shared |
autoCorrect | string | undefined | — | 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](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#autocomplete). | @react-types/shared |
autoFocus | boolean | undefined | — | Whether the element should receive focus on render. | @react-types/shared |
className | ClassNameOrFunction<TextFieldRenderProps> | undefined | 'react-aria-TextField' | The CSS [className](https://developer.mozilla.org/en-US/docs/Web/API/Element/className) for the element. A function may be provided to compute the class based on component state. | react-aria-components |
defaultValue | string | undefined | — | The default value (uncontrolled). | @react-types/shared |
dir | string | undefined | — | — | @react-types/shared |
enterKeyHint | "enter" | "done" | "go" | "next" | "previous" | "search" | "send" | undefined | — | An enumerated attribute that defines what action label or icon to preset for the enter key on virtual keyboards. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/enterkeyhint). | react-aria |
excludeFromTabOrder | boolean | undefined | — | 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. | @react-types/shared |
form | string | undefined | — | 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](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#form). | @react-types/shared |
hidden | boolean | undefined | — | — | @react-types/shared |
id | string | undefined | — | The element's unique identifier. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id). | @react-types/shared |
inert | boolean | undefined | — | — | @react-types/shared |
inputMode | "none" | "search" | "text" | "tel" | "url" | "email" | "numeric" | "decimal" | undefined | — | Hints at the type of data that might be entered by the user while editing the element or its contents. See [MDN](https://html.spec.whatwg.org/multipage/interaction.html#input-modalities:-the-inputmode-attribute). | @react-types/shared |
isDisabled | boolean | undefined | — | Whether the input is disabled. | @react-types/shared |
isInvalid | boolean | undefined | — | Whether the value is invalid. | react-aria-components |
isReadOnly | boolean | undefined | — | Whether the input can be selected but not changed by the user. | @react-types/shared |
isRequired | boolean | undefined | — | Whether user input is required on the input before form submission. | @react-types/shared |
lang | string | undefined | — | — | @react-types/shared |
maxLength | number | undefined | — | The maximum number of characters supported by the input. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefmaxlength). | @react-types/shared |
minLength | number | undefined | — | The minimum number of characters required by the input. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefminlength). | @react-types/shared |
name | string | undefined | — | The name of the input element, used when submitting an HTML form. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefname). | @react-types/shared |
onAnimationEnd | AnimationEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onAnimationEndCapture | AnimationEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onAnimationIteration | AnimationEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onAnimationIterationCapture | AnimationEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onAnimationStart | AnimationEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onAnimationStartCapture | AnimationEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onAuxClick | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onAuxClickCapture | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onBeforeInput | FormEventHandler<HTMLInputElement> | undefined | — | Handler that is called when the input value is about to be modified. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/beforeinput_event). | @react-types/shared |
onBlur | ((e: FocusEvent<HTMLInputElement, Element>) => void) | undefined | — | Handler that is called when the element loses focus. | @react-types/shared |
onChange | ((value: string) => void) | undefined | — | Handler that is called when the value changes. | @react-types/shared |
onClick | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onClickCapture | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onCompositionEnd | CompositionEventHandler<HTMLInputElement> | undefined | — | Handler that is called when a text composition system completes or cancels the current text composition session. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Element/compositionend_event). | @react-types/shared |
onCompositionStart | CompositionEventHandler<HTMLInputElement> | undefined | — | Handler that is called when a text composition system starts a new text composition session. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Element/compositionstart_event). | @react-types/shared |
onCompositionUpdate | CompositionEventHandler<HTMLInputElement> | undefined | — | Handler that is called when a new character is received in the current text composition session. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Element/compositionupdate_event). | @react-types/shared |
onContextMenu | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onContextMenuCapture | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onCopy | ClipboardEventHandler<HTMLInputElement> | undefined | — | Handler that is called when the user copies text. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/oncopy). | @react-types/shared |
onCut | ClipboardEventHandler<HTMLInputElement> | undefined | — | Handler that is called when the user cuts text. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/oncut). | @react-types/shared |
onDoubleClick | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onDoubleClickCapture | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onFocus | ((e: FocusEvent<HTMLInputElement, Element>) => void) | undefined | — | Handler that is called when the element receives focus. | @react-types/shared |
onFocusChange | ((isFocused: boolean) => void) | undefined | — | Handler that is called when the element's focus status changes. | @react-types/shared |
onGotPointerCapture | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onGotPointerCaptureCapture | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onInput | FormEventHandler<HTMLInputElement> | undefined | — | Handler that is called when the input value is modified. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/input_event). | @react-types/shared |
onKeyDown | ((e: KeyboardEvent) => void) | undefined | — | Handler that is called when a key is pressed. | @react-types/shared |
onKeyUp | ((e: KeyboardEvent) => void) | undefined | — | Handler that is called when a key is released. | @react-types/shared |
onLostPointerCapture | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onLostPointerCaptureCapture | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onMouseDown | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onMouseDownCapture | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onMouseEnter | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onMouseLeave | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onMouseMove | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onMouseMoveCapture | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onMouseOut | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onMouseOutCapture | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onMouseOver | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onMouseOverCapture | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onMouseUp | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onMouseUpCapture | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPaste | ClipboardEventHandler<HTMLInputElement> | undefined | — | Handler that is called when the user pastes text. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/onpaste). | @react-types/shared |
onPointerCancel | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerCancelCapture | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerDown | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerDownCapture | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerEnter | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerLeave | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerMove | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerMoveCapture | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerOut | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerOutCapture | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerOver | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerOverCapture | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerUp | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerUpCapture | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onScroll | UIEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onScrollCapture | UIEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onSelect | ReactEventHandler<HTMLInputElement> | undefined | — | Handler that is called when text in the input is selected. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Element/select_event). | @react-types/shared |
onTouchCancel | TouchEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTouchCancelCapture | TouchEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTouchEnd | TouchEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTouchEndCapture | TouchEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTouchMove | TouchEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTouchMoveCapture | TouchEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTouchStart | TouchEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTouchStartCapture | TouchEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTransitionCancel | TransitionEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTransitionCancelCapture | TransitionEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTransitionEnd | TransitionEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTransitionEndCapture | TransitionEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTransitionRun | TransitionEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTransitionRunCapture | TransitionEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTransitionStart | TransitionEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTransitionStartCapture | TransitionEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onWheel | WheelEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onWheelCapture | WheelEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
pattern | string | undefined | — | Regex pattern that the value of the input must match to be valid. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefpattern). | @react-types/shared |
render | DOMRenderFunction<"div", TextFieldRenderProps> | undefined | — | Overrides the default DOM element with a custom render function. This allows rendering existing components with built-in styles and behaviors such as router links, animation libraries, and pre-styled components. Requirements: - You must render the expected element type (e.g. if `<button>` is expected, you cannot render an `<a>`). - Only a single root DOM element can be rendered (no fragments). - You must pass through props and ref to the underlying DOM element, merging with your own prop as appropriate. | react-aria-components |
slot | string | null | undefined | — | 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. | react-aria-components |
spellCheck | string | undefined | — | An enumerated attribute that defines whether the element may be checked for spelling errors. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/spellcheck). | @react-types/shared |
style | StyleOrFunction<TextFieldRenderProps> | undefined | — | The inline [style](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/style) for the element. A function may be provided to compute the style based on component state. | react-aria-components |
translate | "yes" | "no" | undefined | — | — | @react-types/shared |
type | (string & {}) | "search" | "text" | "tel" | "url" | "email" | "password" | undefined | 'text' | The type of input to render. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdeftype). | @react-types/shared |
validate | ((value: string) => ValidationError | true | null | undefined) | undefined | — | 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. | @react-types/shared |
validationBehavior | "native" | "aria" | undefined | 'native' | 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. | react-aria-components |
value | string | undefined | — | The current value (controlled). | @react-types/shared |
Source: packages/ui/src/components/TextField/TextField.tsx:240
Material fidelity and web adaptation
- Family
- Text fields
- Provenance
- spec: Material 3 overview · web: Browser and React Aria semantics · adaptation: m3-ui web adaptation
- Compose mapping
- TextField · OutlinedTextField
- Visual fidelity
- partial: Legacy visual fidelity has not received an explicit reviewed disposition. Current implementation evidence: Implemented as filled and outlined Material text fields with labels, supporting and error text, leading and trailing icons, prefix and suffix content, and single-line or multiline controls.
- Behavior fidelity
- adapted: React Aria owns field, label, description, validation, native input, and textarea semantics. The browser control model is preserved instead of recreating Compose text-input internals.
- Semantics fidelity
- adapted: React Aria owns field, label, description, validation, native input, and textarea semantics. The browser control model is preserved instead of recreating Compose text-input internals.
- Adaptations
- React Aria owns field, label, description, validation, native input, and textarea semantics. The browser control model is preserved instead of recreating Compose text-input internals.
Material provides field hierarchy, variants, visual states, anatomy, and secure-field presentation intent. Native input/textarea editing and React Aria relationships are deliberate web semantics rather than parity failures.
Related components
- Search bar — search-specific input/surface composition.
- Date picker and Time picker — constrained date/time selection.
- Forms and validation — cross-component form ownership and validation composition.