Replace supporting text

forms.errors.replace_supporting_text

Swap supporting text for error text; do not stack error text on top of supporting text (layout shift).

Description

Swap supporting text for error text; do not stack error text on top of supporting text and cause layout shift. In error, supporting text is replaced by error text in the same slot so the layout does not grow a second line under the hint. Fail error stacked on supporting text that shifts the layout.

When to use

Showing Material-style field errors under inputs that already have helper text.

Not when

Persistent instructions that must remain visible alongside a short error.

Agent hint

Swap helper for error in-place; do not stack both and shift the layout.

Pass

In error, supporting text is replaced by error text in the same slot; layout does not grow a second line under the hint.

Fail

Error stacks on supporting text and shifts the layout.

Citations

Material 3 — Text fields

https://m3.material.io/components/text-fields/guidelines