Skip to content
Tutorials Center
My learning

Topics

Lesson 14 of 36 ยท Inputs and Forms

TextField and Text Inputs

Master the Material UI TextField: controlled values, label and helperText, variants, error state, multiline, input adornments, password fields and accessibility.

TextField is the most used form component in Material UI. One component gives you a label that floats, helper text, error styling, a prefix or suffix, and full accessibility wiring. This lesson shows how to use it as a controlled input and how its props map to the pieces you see on screen.

A TextField is a bundle

Internally TextField combines several smaller components: FormControl (state), InputLabel, an Input (or OutlinedInput/FilledInput), and FormHelperText. Normally you never touch them; TextField wires them together and connects the id of the input to the label and helper text for screen readers.

Real MUI code (read-only):

JSX
import TextField from '@mui/material/TextField';

<TextField label="Email" />
<TextField label="Email" variant="filled" />
<TextField label="Email" variant="standard" />

The default variant is outlined. Pick one per application and keep it consistent. Set the default for the whole app in the theme (components.MuiTextField.defaultProps.variant).

Controlled text fields

Like any React input, bind value and onChange to state:

JSX
import { useState } from 'react';

export default function NameField() {
  const [name, setName] = useState('');

  return (
    <TextField
      id="name"
      label="Full name"
      value={name}
      onChange={(event) => setName(event.target.value)}
      fullWidth
    />
  );
}

onChange receives the usual change event, so event.target.value is the text. For an uncontrolled field, drop value/onChange and use defaultValue; read it from a ref (via inputRef) or from FormData on submit. See the controlled and uncontrolled lesson for when each style fits.

Always give each field a label. Placeholder text disappears while typing and is not a replacement. If you need a hidden label, keep label and style around it, or provide slotProps={{ htmlInput: { 'aria-label': 'Search' } }}.

Helper text, errors and required

JSX
<TextField
  label="Password"
  type="password"
  required
  helperText="At least 8 characters"
/>

<TextField
  label="Email"
  value={email}
  onChange={handleChange}
  error={!isValid}
  helperText={isValid ? ' ' : 'Enter a valid email address'}
/>
  • required adds an asterisk to the label and sets the HTML required attribute.
  • error turns the label, border and helper text red. Remember that color alone is not enough for accessibility; the helper text must say what is wrong.
  • helperText={' '} (a space) reserves one line of height so the layout does not jump when an error appears.
  • disabled and slotProps={{ input: { readOnly: true } }} block editing.

Stand-in: a TextField you can edit

Our editor cannot load MUI, so the first example is a stand-in TextField with a floating label, helper text and error state written from scratch. The email field validates as you type.

Stand-in: TextField with label, helper text and error

Multiline, rows and number fields

JSX
<TextField label="Message" multiline minRows={3} maxRows={8} fullWidth />
<TextField label="Age" type="number" slotProps={{ htmlInput: { min: 0, max: 120 } }} />
  • multiline turns the input into an auto-growing textarea; minRows and maxRows limit the height, rows fixes it.
  • type accepts any HTML input type: email, password, tel, url, number, date...
  • Attributes for the native <input> (min, max, step, pattern, maxLength, autoComplete, inputMode) go in slotProps.htmlInput. In older versions this was inputProps. autoComplete="email" and inputMode="numeric" improve mobile keyboards and autofill: always set them for common fields.

Adornments: icons, units and buttons

An adornment is something placed inside the input at the start or end: an icon, a currency symbol, a clear or show-password button. In current versions it goes in slotProps.input:

JSX
import InputAdornment from '@mui/material/InputAdornment';
import IconButton from '@mui/material/IconButton';
import Visibility from '@mui/icons-material/Visibility';
import VisibilityOff from '@mui/icons-material/VisibilityOff';

const [show, setShow] = useState(false);

<TextField
  label="Password"
  type={show ? 'text' : 'password'}
  slotProps={{
    input: {
      startAdornment: <InputAdornment position="start">๐Ÿ”’</InputAdornment>,
      endAdornment: (
        <InputAdornment position="end">
          <IconButton
            aria-label={show ? 'Hide password' : 'Show password'}
            onClick={() => setShow((s) => !s)}
            edge="end"
          >
            {show ? <VisibilityOff /> : <Visibility />}
          </IconButton>
        </InputAdornment>
      ),
    },
  }}
/>

<TextField label="Price" slotProps={{ input: { startAdornment: <InputAdornment position="start">$</InputAdornment> } }} />

In versions before v6 the same options were passed with the InputProps prop. Both mean "props for the Input component inside the TextField".

Stand-in: password field with show toggle

The second stand-in reproduces the show/hide pattern, including the accessible label that changes with state, and a live character counter.

Stand-in: password field with adornment and counter

Sizing and layout

  • size="small" makes the field denser (40px high); margin="dense" and margin="normal" adjust vertical margins when not using Stack.
  • fullWidth stretches the field. Put fields in a Stack spacing={2} or a Grid to lay out forms, as in the layout chapter.
  • color, focused and sx customize appearance.

Common mistakes

  • Using value without onChange (or the other way around): React warns and the field becomes read-only.
  • Setting value={undefined} first and a string later, which switches from uncontrolled to controlled. Start from ''.
  • Hiding the label for design reasons and leaving the field unnamed for screen readers.
  • Using InputProps/inputProps copied from old examples with a new MUI version; check the docs for slotProps.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which two props make a TextField controlled?

    A controlled field gets its value from state through value and updates it in onChange.
  2. 2. What does the error prop do?

    error is only a visual and accessibility state. You decide when it is true and write the message in helperText.
  3. 3. Where do you put start and end adornments like a currency symbol in current MUI versions?

    Adornments are options of the inner Input, passed through slotProps.input; older versions used InputProps.
  4. 4. Why set helperText to a single space when there is no error?

    An empty helper text collapses the line; a space keeps the height stable.

Summary

  • TextField bundles label, input, helper text and error state with correct accessibility wiring.
  • Use variant, size, fullWidth, multiline and type to shape the field; keep the variant consistent.
  • Control it with value and onChange; set error and helperText together.
  • Adornments and native input attributes go through slotProps.input and slotProps.htmlInput (formerly InputProps and inputProps).
  • Always provide a label and the right autoComplete and inputMode.

Next: Select and Autocomplete