Sistema

Text Field

Raw
GuidancelatestM3Retrieved 2026-05-12

Material Design 3 — Text Fields

Overview

Text fields let users enter free-form text. Use when someone needs to type into a UI — contact forms, payment information, search, filters.

Two variants: filled and outlined. Both provide the same functionality; the choice is purely stylistic. Do not mix variants within the same form or immediately adjacent to each other — only separate by region (dialogs vs. the main form below).

Variants

Filled text field

  • Higher visual emphasis
  • Container uses surface-variant fill
  • Active indicator line replaces a border (bottom edge only)
  • Best for: dialogs and short forms where attention should be drawn to the field

Outlined text field

  • Lower visual emphasis
  • No fill; container defined by a 1dp border
  • Best for: long forms with many fields where visual density benefits from de-emphasis

Anatomy

Filled

  1. Container (surface-variant fill, rounded top corners)
  2. Leading icon (optional)
  3. Label text — floats up when populated or focused
  4. Trailing icon (optional)
  5. Active indicator (bottom line: on-surface-variant at rest, primary on focus)
  6. Caret
  7. Input text
  8. Supporting text (optional; below container)

Outlined

  1. Container outline (1dp, outline color at rest; primary on focus)
  2. Leading icon (optional)
  3. Label text — floats into the outline notch when populated or focused
  4. Trailing icon (optional)
  5. Caret
  6. Input text
  7. Supporting text (optional; below container)

States

StateContainer (filled)Outline (outlined)LabelSupporting text
Enabled (empty)surface-variantoutlineon-surface-varianton-surface-variant
Focusedsurface-variantprimary (2dp)primary (floated)on-surface-variant
Populatedsurface-variantoutlineon-surface-variant (floated)on-surface-variant
Errorsurface-varianterror (2dp on focus)errorerror
Disabledon-surface 4% opacityon-surface 12%on-surface 38%on-surface 38%
Read-onlysurface-variantoutlinesame as populated—

Supporting and error text

Supporting text sits below the container and provides hints, character counts, or requirements.

Error state: Replace supporting text with error text — don't add error text in addition to supporting text (the layout would shift). Error text should:

  • Describe how to avoid the error (not just "required field")
  • If multiple errors are possible, describe the most likely one
/* Error colors */
--md-sys-color-error           /* error text and icons */
--md-sys-color-on-error        /* text on error containers */
--md-sys-color-error-container /* error container background */

Icons

  • Leading icon: 20dp; clarifies field purpose (e.g., search, email, phone)
  • Trailing icon: 20dp; typically an action (clear, visibility toggle, calendar open)
  • Both icons use on-surface-variant color at rest; on-surface when active

Label behavior

The label text serves as both placeholder (when empty) and floating label (when populated/focused). It animates between two positions:

  • Rest (empty): Full size, vertically centered — acts as placeholder
  • Populated/focused: Scaled to 75%, positioned at top of container — acts as label

Do not use a separate placeholder attribute for text fields when a label is present — the animated label is the placeholder.

Accessibility

  • Always include a label — do not rely on placeholder text alone
  • Associate helper text with the input using aria-describedby
  • Error state: use aria-invalid="true" and associate error text with aria-describedby
  • Minimum touch target for icons: 48×48dp
  • Avoid hiding labels on small screens — they lose their persistent value