---
title: Form Error Summary
description: An accessible summary of field validation and structured server errors.
icon: circle-alert
related:
  - /form
  - /alert
mode: wide
---

<PoweredBy packages={[{ name: 'React Hook Form', url: 'https://react-hook-form.com/' }]} />

### Installation

Configure the [public Buf package registry](/docs/install#protobuf-and-structured-error-dependencies)
before installing; structured error details depend on its generated Google RPC SDK.

```package-install
bunx shadcn@latest add @redpanda/form-error-summary
```

<ComponentPreview name="form-error-summary-demo" />

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.

```tsx
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.

```tsx
<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

| Prop             | Default                             | Purpose                                                                      |
| ---------------- | ----------------------------------- | ---------------------------------------------------------------------------- |
| `errors`         | Provider errors                     | Field errors; nested paths and all supplied criteria messages are preserved. |
| `submitCount`    | Provider count, otherwise `0`       | Current submission count.                                                    |
| `minSubmitCount` | `1`                                 | Submission threshold before the summary can appear.                          |
| `context`        | —                                   | Structured backend error context.                                            |
| `title`          | Fix the following before submitting | Summary title.                                                               |
| `description`    | —                                   | Secondary helper text.                                                       |
| `focusOnClick`   | `true`                              | Enable field-focus actions.                                                  |
| `labelForPath`   | —                                   | Explicit path-to-label function.                                             |
| `autoLabels`     | —                                   | Protobuf schema used to derive labels.                                       |
| `showDebug`      | `false`                             | Explicit development-only debug opt-in.                                      |
| `testId`         | `form-error-summary`                | Test identifier for the alert root.                                          |

See the primary documentation for [all-criteria validation](https://react-hook-form.com/docs/useform#criteriaMode) and [Connect error details](https://connectrpc.com/docs/web/errors/#error-details).