Skip to content
BigBang

Popular

    ↑↓Navigate↵OpenEscClose
    TR

    Components

    Form

    A form that checks its fields on submit, lists problems in a linked summary and moves focus to it.

    Storybook
    Storybook
    Source
    Source

    Installation

    Section titled “Installation”
    Package
    @bigbang/ui
    Import
    import { Form } from '@bigbang/ui';
    Source
    Form.tsx
    Storybook
    Form · Playground

    Form is in the @bigbang/ui package.

    import { Button, Form, TextInput } from '@bigbang/ui';
    

    <Form onSubmit={(data) => save(data)} errors={serverErrors}>
      <TextInput label="Email" name="email" type="email" required error={serverErrors.email} />
      <Button type="submit">Send</Button>
    </Form>;

    The collectProblems(form, errors) helper reads the problems from a form; use it to draw a custom summary.

    Checking with a schema

    Section titled “Checking with a schema”

    schema takes any Standard Schema v1 schema: Zod, Valibot or ArkType. The library ships no schema package; the app installs one. Zod 4 is the recommended choice for apps (zod/mini on the client), so the same schema also runs on the server. The schema’s output is the third argument of onSubmit.

    import { z } from 'zod';
    

    const schema = z.object({ email: z.email('Enter an email address') });
    

    <Form schema={schema} onSubmit={(data, event, values) => save(values)}>
      <TextInput label="Email" name="email" />
      <Button type="submit">Send</Button>
    </Form>;

    A Valibot schema works through the same schema prop with no adapter; the library runs contract tests with both.

    The formDataToObject and issuesToErrors helpers and the StandardSchemaV1 type are exported too. The type comes from @standard-schema/spec, a types-only package.

    Props

    Section titled “Props”
    onSubmit
    Description
    Called with the form data when the form is submitted without problems. With schema, the third argument is the schema's output.
    Type
    (data: FormData, event: FormEvent<HTMLFormElement>, values: Values) => void
    schema
    Description
    A Standard Schema v1 schema, such as one from Zod, Valibot or ArkType; the library ships no schema package. On submit it checks the form data as an object (a name used more than once becomes a list). Its issues go to the fields by name (the path joined with dots) unless a field has its own error, and join native and server problems in the summary. An async schema is awaited; the submit button is aria-disabled meanwhile.
    Type
    StandardSchemaV1<unknown, Values>
    onInvalid
    Description
    Called with the problems when a submit is stopped.
    Type
    (problems: FormProblem[]) => void
    errors
    Description
    Errors from the server, keyed by field name. When they change after a submit, the summary shows them and takes focus. Also pass each message to its field's error.
    Type
    Readonly<Record<string, string>>
    summary
    Description
    Shows the validation summary above the form and focuses it when a submit is stopped. With false, focus goes to the first invalid field.
    Type
    boolean
    Default
    true
    aria-label
    Description
    Accessible name of the form, such as the page heading.
    Type
    string
    aria-labelledby
    Description
    Id of the heading that names the form.
    Type
    string
    className
    Description
    Added to the form element; use it for layout only.
    Type
    string

    Data attributes

    Section titled “Data attributes”
    • data-component="form": on the form element.
    • data-part: summary, summary-title.