TextField
The <TextField>
is a form component which allows user to enter text with a keyboard. It creates interactive controls for web-based forms in order to accept data from the user.
It is also one of the most powerful and complex elements in all of HTML due to the sheer number of combinations of input types and attributes.
Anatomy
Text fields consist of an input element, which is a container in which the user enters data, and a label which informs the user about the content they need to enter in the field.
<TextField>
automatically manages the relationship between these two elements. It also supports optional description
and error message elements, which can be used to provide more
context about the field, and any validation messages.

Appearance
The appearance of a component can be customized using the variant
and size
props. These props adjust the visual style and dimensions of the component, available values are based on the active theme.
Usage
Use a <TextField>
if a user needs to input unique information that cannot be predicted with a preset of options
(e.g. Radio, Select etc.) and
also a user needs to input memorable data that can be entered more quickly in a free-hand format versus a more
complex
control.
Avoid using <TextField>
if a user can only enter an option from a predefined list then avoid using a free-form
text
input as it is likely to result in an error. Consider using a selection control such as a dropdown, select, or
radio
button group instead.
Label
In general label should be short and precise about what is expected from the user. Avoid unnecessary instructional verbs (doing words) in your labels and hints because it’s already implied by the input field. Avoid placeholder text in most cases, as there’s no need for it (more about it in the next section).


Don’t use unnecessary instructional verbs.
Placeholder
Placeholder text is a short hint displayed inside an input field before a user enters a value. To save space, placeholder text is often used instead of a label, as shown in the first example. This is problematic for the following reasons:
- Placeholder text disappears once a person starts filling in an input field, causing some to forget what the field was for
- Some might miss or skip fields with placeholder text, as it can look like the field has already been pre-filled.
- Placeholder text colour contrast is almost always inaccessible, as it’s very light by design. This means many will struggle to read the label.


Don’t use placeholder text instead of a label.
Additional description
Sometimes the label isn't enough for the user. In this case, to gather additional support for the user we can use the help text. With this we can add helpful hints for the user below the input field. Beside that the help text is placed in close proximity to the associated input field.

Use help text to show an example what's expected.

Textfield with an error
Error messages should let people know that a problem occurred, why it happened, and provide a solution to fix it and move forward.

Never blame the user. Always be positive and helpful.

Be concise and avoid unnecessary words like “please”, “sorry” and “oops”

Use detailed messages instead of global messages.
The error
prop toggles the error state of a field. The errorMessage
prop can then be used to provide feedback to
the user about the error. The message disappears automatically when all requirements are met.
Press Enter
, after typing your text, to trigger the validation.
Props
aria-activedescendant?
string;
aria-autocomplete?
"none" | "inline" | "list" | "both";
aria-controls?
string;
aria-describedby?
string;
aria-details?
string;
aria-errormessage?
string;
aria-haspopup?
boolean | "false" | "true" | "menu" | "listbox" | "tree" | "grid" | "dialog";
aria-label?
string;
aria-labelledby?
string;
autoComplete?
string;
autoCorrect?
string;
autoFocus?
boolean;
defaultValue?
string;
"none"
description?
ReactNode;
dir?
string;
disabled?
boolean;
true
, the input is disabled."false"
enterKeyHint?
"enter" | "done" | "go" | "next" | "previous" | "search" | "send";
error?
boolean;
true
, the field is considered invalid and if set the errorMessage
is shown instead of the description
."false"
errorMessage?
ReactNode | ((v: ValidationResult) => ReactNode);
excludeFromTabOrder?
boolean;
form?
string;
<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.hidden?
boolean;
id?
string;
inert?
boolean;
inputMode?
"none" | "search" | "text" | "url" | "tel" | "email" | "numeric" | "decimal";
label?
ReactNode;
lang?
string;
max?
string;
"none"
maxLength?
number;
min?
string;
"none"
minLength?
number;
name?
string;
onAnimationEnd?
AnimationEventHandler<HTMLDivElement>;
onAnimationEndCapture?
AnimationEventHandler<HTMLDivElement>;
onAnimationIteration?
AnimationEventHandler<HTMLDivElement>;
onAnimationIterationCapture?
AnimationEventHandler<HTMLDivElement>;
onAnimationStart?
AnimationEventHandler<HTMLDivElement>;
onAnimationStartCapture?
AnimationEventHandler<HTMLDivElement>;
onAuxClick?
MouseEventHandler<HTMLDivElement>;
onAuxClickCapture?
MouseEventHandler<HTMLDivElement>;
onBeforeInput?
FormEventHandler<HTMLInputElement>;
onBlur?
(e: FocusEvent<HTMLInputElement, Element>) => void;
onChange?
(value: string) => void;
onClick?
MouseEventHandler<HTMLDivElement>;
onClickCapture?
MouseEventHandler<HTMLDivElement>;
onCompositionEnd?
CompositionEventHandler<HTMLInputElement>;
onCompositionStart?
CompositionEventHandler<HTMLInputElement>;
onCompositionUpdate?
CompositionEventHandler<HTMLInputElement>;
onContextMenu?
MouseEventHandler<HTMLDivElement>;
onContextMenuCapture?
MouseEventHandler<HTMLDivElement>;
onCopy?
ClipboardEventHandler<HTMLInputElement>;
onCut?
ClipboardEventHandler<HTMLInputElement>;
onDoubleClick?
MouseEventHandler<HTMLDivElement>;
onDoubleClickCapture?
MouseEventHandler<HTMLDivElement>;
onFocus?
(e: FocusEvent<HTMLInputElement, Element>) => void;
onFocusChange?
(isFocused: boolean) => void;
onGotPointerCapture?
PointerEventHandler<HTMLDivElement>;
onGotPointerCaptureCapture?
PointerEventHandler<HTMLDivElement>;
onInput?
FormEventHandler<HTMLInputElement>;
onKeyDown?
(e: KeyboardEvent) => void;
onKeyUp?
(e: KeyboardEvent) => void;
onLostPointerCapture?
PointerEventHandler<HTMLDivElement>;
onLostPointerCaptureCapture?
PointerEventHandler<HTMLDivElement>;
onMouseDown?
MouseEventHandler<HTMLDivElement>;
onMouseDownCapture?
MouseEventHandler<HTMLDivElement>;
onMouseEnter?
MouseEventHandler<HTMLDivElement>;
onMouseLeave?
MouseEventHandler<HTMLDivElement>;
onMouseMove?
MouseEventHandler<HTMLDivElement>;
onMouseMoveCapture?
MouseEventHandler<HTMLDivElement>;
onMouseOut?
MouseEventHandler<HTMLDivElement>;
onMouseOutCapture?
MouseEventHandler<HTMLDivElement>;
onMouseOver?
MouseEventHandler<HTMLDivElement>;
onMouseOverCapture?
MouseEventHandler<HTMLDivElement>;
onMouseUp?
MouseEventHandler<HTMLDivElement>;
onMouseUpCapture?
MouseEventHandler<HTMLDivElement>;
onPaste?
ClipboardEventHandler<HTMLInputElement>;
onPointerCancel?
PointerEventHandler<HTMLDivElement>;
onPointerCancelCapture?
PointerEventHandler<HTMLDivElement>;
onPointerDown?
PointerEventHandler<HTMLDivElement>;
onPointerDownCapture?
PointerEventHandler<HTMLDivElement>;
onPointerEnter?
PointerEventHandler<HTMLDivElement>;
onPointerLeave?
PointerEventHandler<HTMLDivElement>;
onPointerMove?
PointerEventHandler<HTMLDivElement>;
onPointerMoveCapture?
PointerEventHandler<HTMLDivElement>;
onPointerOut?
PointerEventHandler<HTMLDivElement>;
onPointerOutCapture?
PointerEventHandler<HTMLDivElement>;
onPointerOver?
PointerEventHandler<HTMLDivElement>;
onPointerOverCapture?
PointerEventHandler<HTMLDivElement>;
onPointerUp?
PointerEventHandler<HTMLDivElement>;
onPointerUpCapture?
PointerEventHandler<HTMLDivElement>;
onScroll?
UIEventHandler<HTMLDivElement>;
onScrollCapture?
UIEventHandler<HTMLDivElement>;
onSelect?
ReactEventHandler<HTMLInputElement>;
onTouchCancel?
TouchEventHandler<HTMLDivElement>;
onTouchCancelCapture?
TouchEventHandler<HTMLDivElement>;
onTouchEnd?
TouchEventHandler<HTMLDivElement>;
onTouchEndCapture?
TouchEventHandler<HTMLDivElement>;
onTouchMove?
TouchEventHandler<HTMLDivElement>;
onTouchMoveCapture?
TouchEventHandler<HTMLDivElement>;
onTouchStart?
TouchEventHandler<HTMLDivElement>;
onTouchStartCapture?
TouchEventHandler<HTMLDivElement>;
onTransitionCancel?
TransitionEventHandler<HTMLDivElement>;
onTransitionCancelCapture?
TransitionEventHandler<HTMLDivElement>;
onTransitionEnd?
TransitionEventHandler<HTMLDivElement>;
onTransitionEndCapture?
TransitionEventHandler<HTMLDivElement>;
onTransitionRun?
TransitionEventHandler<HTMLDivElement>;
onTransitionRunCapture?
TransitionEventHandler<HTMLDivElement>;
onTransitionStart?
TransitionEventHandler<HTMLDivElement>;
onTransitionStartCapture?
TransitionEventHandler<HTMLDivElement>;
onWheel?
WheelEventHandler<HTMLDivElement>;
onWheelCapture?
WheelEventHandler<HTMLDivElement>;
pattern?
string;
placeholder?
string;
"none"
readOnly?
boolean;
true
, the input is readOnly."false"
ref?
Ref<HTMLInputElement>;
ref.current
to null
(or call the ref with null
if you passed a callback ref).
@see {@link https://react.dev/learn/referencing-values-with-refs#refs-and-the-dom React Docs}required?
boolean;
true
, the input is required."false"
spellCheck?
string;
translate?
"yes" | "no";
type?
"search" | "text" | "url" | "tel" | "email" | "password" | (string & {});
validate?
(value: string) => true | ValidationError | null;
validationBehavior="native"
. For realtime validation, use the isInvalid
prop instead.validationBehavior?
"native" | "aria";
'native'
value?
string;
"none"
width?
WidthProp;
"full"