toc

Text field

Text fields let people enter and edit text.

<md-gb-text-field label="Name"></md-gb-text-field>

Install with shadcn/ui: npx shadcn@latest add https://material-web.dev/3.0/r/md-text-field.json (setup)

Usage guidelines

Link to “Usage guidelines”

Filled or outlined. Filled fields have more visual weight and suit most forms. Outlined fields are lighter and work where many fields sit together. Don't mix them in one form.
Label every field. The label floats above the text once the field has a value or focus. Use a placeholder only as an example of the input, never in place of the label.
Help before and after. Use supporting text for hints, and explain what went wrong in an error.

Anatomy

Link to “Anatomy”

A text field has a label, the input, optional icons and prefix or suffix text, and supporting text.

language

link

<md-gb-text-field label="Website" prefix-text="https://" suffix-text=".com" supporting-text="Your public address">
  <md-gb-icon slot="leading-icon">language</md-gb-icon>
  <md-gb-icon slot="trailing-icon">link</md-gb-icon>
</md-gb-text-field>

Examples

Link to “Examples”

Variants

Link to “Variants”

Text fields are filled by default. Set variant="outlined" for an outlined field. Add placeholder for an example of the input.

<md-gb-text-field label="Email" variant="outlined" placeholder="name@example.com"></md-gb-text-field>

Input types

Link to “Input types”

type changes the keyboard and the built-in validation. It can be text (default), email, number, password, search, tel, url or textarea.

<md-gb-text-field type="password" label="Password"></md-gb-text-field>
<md-gb-text-field type="email" label="Email"></md-gb-text-field>
<md-gb-text-field type="number" label="Quantity" min="1" max="10"></md-gb-text-field>

Textarea

Link to “Textarea”

type="textarea" makes a multi-line field. Set rows for its height.

<md-gb-text-field type="textarea" label="Message" rows="3"></md-gb-text-field>

Icons

Link to “Icons”

Icons in the leading-icon and trailing-icon slots sit before and after the input. A trailing icon button needs an aria-label.

cancel

<md-gb-text-field label="Search" value="Pasta">
  <md-gb-icon slot="leading-icon">search</md-gb-icon>
  <md-gb-icon-button slot="trailing-icon" aria-label="Clear">
    <md-gb-icon>cancel</md-gb-icon>
  </md-gb-icon-button>
</md-gb-text-field>

Prefix and suffix

Link to “Prefix and suffix”

prefix-text and suffix-text show fixed text around the input, such as a currency or a domain.

<md-gb-text-field label="Amount" prefix-text="$" value="100"></md-gb-text-field>
<md-gb-text-field label="Email" suffix-text="@example.com" value="ada"></md-gb-text-field>

Supporting text and counter

Link to “Supporting text and counter”

supporting-text shows a hint below the field. A maxlength adds a character counter.

<md-gb-text-field label="Bio" maxlength="20" value="Hello" supporting-text="Tell us about yourself"></md-gb-text-field>

Error and validation

Link to “Error and validation”

Set error and error-text to show an error yourself. A field also validates with the browser's constraint attributes (required, pattern, minlength, min, max) when its form is submitted or reportValidity() is called, and shows the message in its supporting text.

<md-gb-text-field label="ZIP code" value="1234" error error-text="Enter a 5-digit ZIP code"></md-gb-text-field>

Required

Link to “Required”

required adds an asterisk to the label and makes an empty field invalid. Add no-asterisk to hide it.

<md-gb-text-field label="Username" required supporting-text="Required"></md-gb-text-field>

Disabled and read-only

Link to “Disabled and read-only”

A disabled field can't be focused. A readonly field can be focused and selected but not edited.

<md-gb-text-field label="Account" value="Locked" disabled></md-gb-text-field>
<md-gb-text-field label="Order number" value="A-1042" readonly></md-gb-text-field>

In a form

Link to “In a form”

Fields take part in a form through their name and value, and the form checks them on submit.

<form>
  <md-gb-text-field name="name" label="Name" required></md-gb-text-field>
  <md-gb-text-field name="email" type="email" label="Email" required></md-gb-text-field>
  <md-gb-button type="submit">Subscribe</md-gb-button>
</form>

Density

Link to “Density”

Set density from 0 (default) to -3 to remove 4px of height per step.

<md-gb-text-field label="Name" density="-2"></md-gb-text-field>

Accessibility

Link to “Accessibility”

The field's label names the input. For a field with an external label, add an aria-label.
Supporting and error text are linked to the input, so screen readers read them with it. An invalid field is marked with aria-invalid.
Icon buttons in a slot need their own aria-label.

<md-gb-text-field aria-label="Search the catalog" placeholder="Search"></md-gb-text-field>

Compatibility

Link to “Compatibility”

Material Design 3Spec checked87% tokens

69 of 358 buildable spec units are tested, 14 are excluded with a written reason and 0 are uncovered (the target is 0). 130 of 150 token declarations match the spec (87%), and 20 have no spec token.

text-fields on m3.material.io (opens in a new tab) How compliance is measured

BaselineWidely availableChrome 124Edge 124Firefox 125Safari 17.4

The component’s own CSS and JavaScript rely only on web platform features that are Baseline widely available: it works in Chrome 124, Edge 124, Firefox 125, Safari 17.4 and later.

Newer features it uses where the browser has them (progressive enhancements):

Cursor styles (opens in a new tab) Limited availability degrades safely where it is missing
field-sizing (opens in a new tab) Newly available degrades safely where it is missing
resize (CSS property) (opens in a new tab) Limited availability degrades safely where it is missing

Browser support Learn more about Baseline (opens in a new tab)

WAI-ARIAaxe and ARIA 1.3 passAlert

Roles the component renders: alert (opens in a new tab), textbox (opens in a new tab).

Follows the WAI-ARIA Authoring Practices: Alert (opens in a new tab).

3 rendered states run through axe-core and the WAI-ARIA 1.3 role and attribute rules in a real browser, with no known gaps.

WAI-ARIA 1.3 (opens in a new tab) ARIA Authoring Practices (opens in a new tab) Accessibility

Lighthouse99 · 100 · 100 · 100

Performance
Accessibility
Best practices
SEO

Audits under 90:

Eliminate render-blocking resources
Minify JavaScript
Reduce unused CSS
Enable text compression
Network dependency tree
Render blocking requests

Lighthouse 12.8.2 (desktop, 2026-11-08) on the component alone: its first example on a page of its own, without this site's shell. The modules are the development build (not bundled or minified), so the performance score is indicative.

Open the test page About Lighthouse (opens in a new tab)

API reference

Link to “API reference”

<md-gb-text-field>

Link to “<md-gb-text-field>”

A Material Design text field (filled or outlined).

Properties

Link to “Properties”

Property	Attribute	Type	Default
`autocomplete` The input's `autocomplete` hint.	`autocomplete`	`string`	`''`
`cols` The number of columns of a `type="textarea"` field.	`cols`	`number`	`20`
`density` The density, from 0 (default) to -3. Each step down removes 4px from the container height (56px), half above and half below the content; text keeps its size. Values are clamped to that range. text-fields.md "Avoid applying density by default": dense fields are below the 48x48 CSS pixel target, so let people opt in (a denser layout or theme) and keep the controls that change it at 48x48.	`density`	`Density`
`error` Whether the field is in a visually invalid state. Overrides the error state set by `reportValidity()`.	`error`	`boolean`	`false`
`errorIcon` When the error icon shows in the trailing edge: `always` (default) in the error state, or `focus` only while the field has focus. Its space stays reserved, so focusing the field does not move the text.	`error-icon`	`ErrorIconVisibility`	`'always'`
`errorText` The message that replaces the supporting text while `error` is true. If empty, the supporting text keeps showing. Overrides the message shown by `reportValidity()`.	`error-text`	`string`	`''`
`hasLeadingIcon` Whether a leading icon is slotted. Set it for SSR.	`has-leading-icon`	`boolean`	`false`
`hasTrailingIcon` Whether a trailing icon is slotted. Set it for SSR.	`has-trailing-icon`	`boolean`	`false`
`inputMode` MDN Reference	`inputmode`	`string`	`''`
`label` The floating label. It is also the input's accessible name, unless `aria-label` is set.	`label`	`string`	`''`
`max` The greatest permitted value.	`max`	`string`	`''`
`maxLength` The maximum number of characters; shows a character counter. -1 for none.	`maxlength`	`number`	`-1`
`min` The least permitted value.	`min`	`string`	`''`
`minLength` The minimum number of characters. -1 for none.	`minlength`	`number`	`-1`
`multiple` Whether an email field accepts multiple addresses.	`multiple`	`boolean`	`false`
`noAsterisk` Hides the asterisk added to the label of a required field.	`no-asterisk`	`boolean`	`false`
`noSpinner` Hides the spinner of `type="number"` fields.	`no-spinner`	`boolean`	`false`
`pattern` A regular expression the value must match.	`pattern`	`string`	`''`
`placeholder` Hint text shown in the input while it is empty and the label is floated (or there is no label).	`placeholder`	`string`	`''`
`prefixText` Text shown before the input value, such as a currency symbol.	`prefix-text`	`string`	`''`
`readOnly` Whether the value cannot be edited.	`readonly`	`boolean`	`false`
`required` Whether a value is required for form submission. Adds an asterisk to the label.	`required`	`boolean`	`false`
`rows` The number of rows of a `type="textarea"` field.	`rows`	`number`	`2`
`step` The step between permitted numeric values.	`step`	`string`	`''`
`suffixText` Text shown after the input value, such as a unit.	`suffix-text`	`string`	`''`
`supportingText` Additional information shown below the field.	`supporting-text`	`string`	`''`
`supportingTextVisibility` When the supporting text shows: `always` (default), or `focus` only while the field has focus (text-fields-aed1bf). Its space stays reserved so the layout does not move, it stays in the input's accessible description, and an error message always shows.	`supporting-text-visibility`	`SupportingTextVisibility`	`'always'`
`textDirection` Overrides the input's CSS `direction`.	`text-direction`	`string`	`''`
`type` The input type, `text` by default. `textarea` renders a multi-line `<textarea>`.	`type`	`TextFieldType`	UnsupportedTextFieldType
`value` The current value. It is always a string.	`value`	`string`	`''`
`variant` The variant: `filled` (default) or `outlined`.	`variant`	`TextFieldVariant`	`'filled'`

Slots

Link to “Slots”

Slot	Description
`leading-icon`	An icon (or icon button) before the input.
`trailing-icon`	An icon (or icon button) after the input, such as a clear, visibility or error icon.

Events

Link to “Events”

Event	Description
`change` Event	The native `change` event.
`input` InputEvent	The native `input` event.
`invalid` Event	Fired when `checkValidity()` or `reportValidity()` finds the field invalid.
`select` Event	The native `select` event.

Methods

Link to “Methods”

Method	Description
`focus` (options?: FocusOptions) => void	MDN Reference
`reset` () => void	Resets the value to the `value` attribute and clears native errors.
`select` () => void	Selects all the text.
`setCustomValidity` (error: string) => void	Sets the element's constraint validation error message. When set to a non-empty string, `validity.customError` will be true and `validationMessage` will display the provided error. Use this method to customize error messages reported. https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/setCustomValidity
`setRangeText` { (replacement: string): void; (replacement: string, start: number, end: number, selectionMode?: SelectionMode): void; }	Replaces a range of text with a new string.
`setSelectionRange` (start: number, end: number, direction?: "none"	"forward"
`showPicker` () => void	Shows the browser picker of a date, time or color field.
`stepDown` (n?: number) => void	Decrements a numeric value by `step`, `n` times.
`stepUp` (n?: number) => void	Increments a numeric value by `step`, `n` times.

CSS parts

Link to “CSS parts”

Part	Description
`::part(container)`	The field's container.
`::part(counter)`	The character counter.
`::part(input)`	The native `<input>` or `<textarea>`.
`::part(label)`	The floating label.
`::part(supporting-text)`	The supporting or error text.

CSS custom properties

Link to “CSS custom properties”

Property	Description
`--active-indicator-color`	Filled active indicator color.
`--active-indicator-height`	Filled active indicator thickness.
`--affix-space`	Space between the prefix/suffix and the input.
`--bottom-space`	Space below the input.
`--caret-color`	Input caret color.
`--container-color`	Container background color.
`--container-height`	Single-line container height.
`--container-shape`	Container corner radius.
`--counter-space`	Space between the supporting text and counter.
`--density-step`	Container height removed per density step.
`--icon-input-space`	Space between an icon and the input.
`--icon-leading-space`	Start padding before a leading icon.
`--icon-trailing-space`	End padding after a trailing icon.
`--input-text`	Input typography.
`--input-text-axes`	Input font variation settings.
`--input-text-color`	Input text color.
`--input-text-placeholder-color`	Placeholder color.
`--input-text-prefix-color`	Prefix text color.
`--input-text-suffix-color`	Suffix text color.
`--input-text-tracking`	Input letter spacing.
`--label-text`	Resting label typography.
`--label-text-axes`	Label font variation settings.
`--label-text-color`	Label color.
`--label-text-populated-line-height`	Floated label line height.
`--label-text-populated-size`	Floated label font size.
`--label-text-tracking`	Label letter spacing.
`--leading-icon-color`	Leading icon color.
`--leading-icon-size`	Leading icon size.
`--leading-space`	Start padding without a leading icon.
`--outline-color`	Outlined container outline color.
`--outline-label-padding`	Space around the floated label in the outline notch.
`--outline-width`	Outlined container outline width.
`--state-layer-color`	Hover state layer color (filled).
`--supporting-text`	Supporting text typography.
`--supporting-text-axes`	Supporting text font variation settings.
`--supporting-text-color`	Supporting text color.
`--supporting-text-top-space`	Space above the supporting text.
`--supporting-text-tracking`	Supporting text letter spacing.
`--top-space`	Space above the content (filled: above the floated label).
`--trailing-icon-color`	Trailing icon color.
`--trailing-icon-size`	Trailing icon size.
`--trailing-space`	End padding without a trailing icon.