Helper text

v1.0.0 | View in Storybook

​

When to use

• Format requirements the user needs before they start typing, e.g., “Password must be at least 8 characters”.
• Validation feedback after a field has been interacted with, e.g., “Please enter a valid email address format (e.g., name@example.com).”
• Contextual hints that reduce input errors, e.g., “Enter the 9 digit ID found in user settings.”

​

When not to use

• Long explanations — use a Tooltip or Popover instead.
• Page-level or section-level guidance — use Alert or plain text.

​

Dos and don’ts

• Do show format hints upfront, not only after the user has already made a mistake.
• Do replace the default helper text with the error message when validation fails — don’t stack both.
• Do keep it to one or two short sentences — if you need more than that, the field or the form design probably needs rethinking.
• Do ensure error messages say what’s wrong and how to fix it, not just that something is wrong (“Enter a valid email address” not “Invalid input”).
• Don’t use it for information the user doesn’t need to complete the field.
• Don’t write helper text that just restates the label in different words.

​

Often used with

Tied to a single field: always with that control’s Label and one of Input, Textarea, Select, Combobox, Checkbox / Radio group, or Switch.

​

Accessibility

• Match input references: Ensure every helper text <span> or <p> has a unique id matching its input’s ARIA reference.
• Preserve instruction context on error: When an error appears, append the error element’s id to aria-describedby or switch to aria-errormessage dynamically without removing the original instruction id.

​

Visual examples

The examples below are interactive and follow the doc site’s theming: light mode when the docs site is in light mode, and dark mode when you switch the docs site to dark mode.

​

Size xs

Use the extra-small size for dense forms, compact tables, or inline field groups where vertical space is limited but guidance is still needed.

​

Size sm

Use the small size as the default for most form fields—it balances readability with a compact footprint below standard inputs and selects.

​

Error state

Show the error state after validation fails to explain what went wrong and how to fix it, replacing the default helper text rather than stacking both.

​

Success

Use the success state to confirm that a value passed validation—for example, after an async username check or password strength requirement is met.

​

With custom icon

Add a custom icon when the default state icons do not match your product vocabulary or when a specific metaphor helps users scan feedback faster.

​

Warning

Use the warning state for values that are valid but may cause issues—such as a password that meets minimum requirements but is still weak.

​

Tip

Use the tip variant for optional guidance that helps users complete the field more efficiently without implying an error or success condition.

​

No icon

Omit the icon when the message is neutral guidance and a leading glyph would add visual noise without aiding comprehension.

​

Long text

Reserve longer helper text for constraints that truly need explanation; if copy grows beyond one or two sentences, reconsider the field design or link to a Popover.

​

Size comparison

Compare sizes side by side when choosing typography for a form system so helper text stays visually aligned with its associated control.

​

All states

Review all states together when auditing form feedback patterns to ensure consistent tone, color, and icon usage across your product.