Form Error Summary

An accessible summary of field validation and structured server errors.

Powered by

React Hook Form

Installation

Configure the public Buf package registry before installing; structured error details depend on its generated Google RPC SDK.

npx shadcn@latest add @redpanda/form-error-summary

pnpm dlx shadcn@latest add @redpanda/form-error-summary

yarn dlx shadcn@latest add @redpanda/form-error-summary

bunx shadcn@latest add @redpanda/form-error-summary

nubx shadcn@latest add @redpanda/form-error-summary

aube dlx shadcn@latest add @redpanda/form-error-summary

The example validates locally, then simulates a structured rate-limit response. It does not send profile data to a server.

Usage

Place the summary inside your existing FormProvider or registry Form. It subscribes to field errors and submit count directly, including in React Compiler builds; the parent does not need to read formState to force updates.

import { FormErrorSummary } from '@/components/ui/form-error-summary';
<FormErrorSummary />;

The summary is hidden before the first submission by default. With React Hook Form’s criteriaMode: 'all', it includes every distinct supplied message for each field, not just the first criterion. Identical primary and criterion messages appear once. An error leaf without a message remains visible as “Invalid value.”

For standalone use, provide both errors and submitCount. Explicit props take precedence over provider values.

<FormErrorSummary errors={{ username: { type: 'required', message: 'Enter a username.' } }} submitCount={1} />

Field focus

Activating a field error focuses the corresponding name or data-name control. A summary inside a native form resolves that form’s controls, including inputs associated through the native form attribute, rather than selecting the first matching name elsewhere on the page.

Outside a form, the summary can focus an unambiguous document target. If the same field appears in multiple forms, it reports the ambiguity instead of focusing a potentially unrelated form. Missing or unavailable targets also produce visible feedback. Use focusOnClick={false} for a noninteractive list.

labelForPath takes precedence over autoLabels. autoLabels reads protobuf summary-label annotations, with a humanized leaf-name fallback. Without either option, labels remain the original field paths.

Structured server context

Pass a ConnectErrorContext from extractConnectErrorContext in @/lib/format-error. The summary can display the backend message, every precondition and quota violation, help links, a copyable request ID, and a retry hint for resource-exhausted responses. Text is rendered as text, not HTML.

The retry hint counts down while the summary is hidden by minSubmitCount, stops at zero, and resets when the supplied retry duration changes. It is informational: it does not disable submission or automatically retry a request.

Debug visibility

Backend debug details are absent by default, including during server rendering. Enable showDebug only from trusted development configuration, with the same value on the server and during hydration. Do not expose private backend diagnostics through a user-controlled toggle.

The demo’s toggle reveals fabricated development data only. JSON-like detail strings remain literal text, and stack entries use an ordered list of code fragments.

Props

See the primary documentation for all-criteria validation and Connect error details.