FormError

Connect validation and server errors

FormError reads a field message from Form. Use validation, setError and clearErrors to manage its content, and named-part classes to customize its presentation.

FormError — show and customize field feedback

FormError reads errors[name] from its parent Form. Its required name must match the registered field key. It renders a role=alert paragraph only when that field has a message; register connects the field's aria-describedby and aria-invalid attributes to it.

Return messages from validate or call form.setError(name, message) for a server response. Editing a registered field clears its error; clearErrors removes the message explicitly. Use className or classNames.error to style the message while preserving its association and alert role.

"use client";

import { Button, Form, FormError, FormSubmit, Input, useForm } from "@pimolu/react";

export function FieldError() {
  const form = useForm({
    defaultValues: { name: "" },
    validate: (values) => values.name.trim() ? {} : { name: "Enter your name." },
  });
  return (
    <Form form={form} autoComplete="off" className="grid gap-4">
      <Input label="Name" {...form.register("name")} />
      <FormError name="name" classNames={{ error: "profile-error" }} />
      <div className="flex flex-wrap gap-3">
        <FormSubmit>Validate</FormSubmit>
        <Button
          onClick={() => form.setError(
            "name",
            "This name is already used (simulated server response)."
          )}
        >
          Simulate server error
        </Button>
        <Button appearance="ghost" onClick={() => form.clearErrors("name")}>Clear error</Button>
      </div>
      <style>
        {
          `.profile-error {
  font-weight: 600;
  border-inline-start: 3px solid currentColor;
  padding-inline-start: 12px;
}`
        }
      </style>
    </Form>
  );
}

New to Pimolu? Follow the Quick start or the Next.js guide for the shared stylesheet and application provider.

More examples

Different configurations and compositions using the real Pimolu API. Each preview runs independently and follows the site appearance.

Usage

Place FormError inside Form with a name matching a field key. It reads form.errors[name] and renders nothing when there is no message. Return an error map from validate or call form.setError(name, message) after a server response.

Spread form.register(name) onto a native-event input such as Input. Registration connects aria-invalid and aria-describedby to the message. For controls exposing onValueChange, connect form.values, setValue and those ARIA attributes explicitly.

Editing a registered field or calling setValue clears its error. clearErrors(name) removes one error; clearErrors() removes all. FormError only renders feedback: it does not run validation or submit the form.

Customize the message with className or classNames.error, or provide Form-level classNames.error for shared styling. Preserve the generated id and alert role. The current API displays a text message; it does not accept arbitrary children or Button props.

API reference

Generated from the public TypeScript declarations. Native HTML attributes are inherited where the component extends them; this reference includes Pimolu props and selected common native attributes.

Accessibility

• Keep the error next to its field and explain how to correct it. The message is a paragraph with role=alert and a stable id associated with the registered control.
• Do not rely on color alone. Validation does not automatically focus the first invalid field; decide how your application should handle focus and an error summary.

Related components