Forms
Validation Message
Validation Message is inline typed feedback paired with a field — error, warning, success, or info — with icon and text.
Type (Error/Warning/Success/Info) — 4 variants
stableReact AvailableFigma AvailableDocs Partial
- React last updated
- 2026-08-30
- Documentation last updated
- 2026-06-01
- Accessibility target
- WCAG 2.2 AA (target)
- Version
- 1.0.0
Known open questions
- Info type icon swap to dedicated Info icon is pending Figma confirmation.
- Warning icon contrast remains a separate Figma-first task; React icons stay on semantic-feedback-warning.
Purpose
Inline feedback text paired with a form field, communicating error, warning, success, or informational status.
Anatomy
ValidationMessage = Phosphor icon + message text. Icons are decorative; meaning comes from text.
Variants and states
error · warning · success · info
When to use
Directly below or near a field to explain its status. Complete fields (Text Input) and Form Field already render their own `error` through Validation Message, so use a standalone Validation Message only where no such field renders it — for example beside a custom control wired through Form Field, or for a form-level message.
When not to use
Page-level or app-level notifications unrelated to a specific field (use Alert or Toast instead).
Accessibility
Must be programmatically associated with its field via aria-describedby, not just visually placed nearby.
Keyboard behavior
Not focusable. Live announcement behavior is controlled by the announce prop.
Common mistakes
Relying on icon/color alone to convey meaning without real explanatory text. Adding a separate Validation Message beside Text Input or Form Field for an error they already render. Rendering announce="assertive" for an error that is already on screen at first render: keep the default "off" for static errors and use "assertive" only for an error introduced after the page is shown, such as after a failed submit.
Properties
Type as variants. Message (text).
Tokens used
component/validation-message/error/textcomponent/validation-message/warning/textcomponent/validation-message/success/textcomponent/validation-message/info/textcomponent/validation-message/textsemantic/feedback/warningsemantic/feedback/successsemantic/feedback/info
Known limitation
Info type currently reuses the WarningCircle icon — Icon/Info now exists and should be swapped in.
Component API
| Prop | Type | Default | Description |
|---|---|---|---|
| type | "error" | "warning" | "success" | "info" | "error" | Visual and semantic feedback type. |
| announce | "off" | "polite" | "assertive" | "off" | Live region behavior. Keep the default "off" for an error that is already on screen at first render; use assertive only for an error introduced after the page is shown, such as after a failed submit. |
| id | string | — | Used by aria-describedby on the related control. |
React example
Copy React example
import { ValidationMessage } from "@/components/ui/ValidationMessage";
export function Example({ submitError }: { submitError?: string }) {
// Rendered only after a failed submit, so the error is introduced dynamically
// and "assertive" is appropriate. An error already on screen at first render
// keeps the default announce="off".
return submitError ? (
<ValidationMessage id="form-error" type="error" announce="assertive">
{submitError}
</ValidationMessage>
) : null;
}