Form

A <form> that knows which of its fields is wrong. A submit collects every field's validity at once, focuses the first that failed, and errors from a server land on the field they belong to.

import { Button, Form, TextField } from 'neba';

<Form onSubmit={(values) => save(values)}>
  <TextField label="Email" name="email" type="email" required />
  <Button type="submit">Create account</Button>
</Form>;

Props

Prop	Type	Default	Description
onSubmit	(values: Record<string, unknown>) => void	—	Called only when every field is valid, with the form's values keyed by each field's name. The native submit event is prevented, so nothing navigates
validationMode	'onSubmit' | 'onBlur' | 'onChange'	'onSubmit'	When a field validates. onSubmit means on submit and on every change afterwards, onBlur when it loses focus, onChange on every keystroke
errors	Record<string, string | string[]>	—	Errors from outside the browser's own validation, keyed by the name of the field each belongs to. Shown on that field and cleared as soon as it changes
sizeshared	'xs' | 'sm' | 'md' | 'lg' | 'xl'	'md'	The gap between the children. A form is a stack, and this is which rung it stacks on
children	ReactNode	—	The fields and the submit button

Every native <form> attribute passes through, apart from onSubmit, which is handed the values rather than the event. It is not a form library: there is no schema, no resolver and no field array here. A project that wants those keeps them and hands the result to errors, which is the seam this is built around.

The children are laid out as a column with the gap size names. Put a Grid or a Fieldset inside for anything else.

Examples

onSubmit

Called only when every field is valid, with the form's values keyed by each field's name. The native submit event is prevented, so nothing navigates.

validationMode

onSubmit is the default and the only one that does not tell somebody their email is wrong while they are still typing it: after the first submit, fields re-validate on change. onBlur validates when a field loses focus, onChange on every keystroke.

import { Button, Form, TextField } from 'neba';

const modes = ['onSubmit', 'onBlur', 'onChange'] as const;

export default function FormValidationMode() {
  return (
    <div className="grid w-full max-w-2xl grid-cols-1 gap-6 sm:grid-cols-3">
      {modes.map((mode) => (
        <Form key={mode} size="sm" validationMode={mode} onSubmit={() => {}}>
          <TextField
            size="sm"
            label={mode}
            name="email"
            type="email"
            required
            placeholder="[email protected]"
          />
          <Button size="sm" type="submit">
            Submit
          </Button>
        </Form>
      ))}
    </div>
  );
}

errors

Errors from outside the browser's own validation (a server, a form action, a schema) keyed by the name of the field each belongs to. They render on that field and clear as soon as it changes.

import { useState } from 'react';
import { Button, Form, TextField } from 'neba';

/** Stands in for a server that already knows this address. */
const TAKEN = '[email protected]';

export default function FormErrors() {
  const [errors, setErrors] = useState<Record<string, string>>({});

  return (
    <Form
      className="w-full max-w-sm"
      errors={errors}
      onSubmit={(values) =>
        setErrors(values.email === TAKEN ? { email: 'That address is already taken.' } : {})
      }
    >
      <TextField
        label="Email"
        name="email"
        type="email"
        required
        defaultValue={TAKEN}
        description={`Submit as ${TAKEN} to see the server answer.`}
      />
      <Button type="submit">Check</Button>
    </Form>
  );
}

Accessibility

• A failed submit moves focus to the first invalid field, so the reader is taken to the problem rather than told there is one.
• Each message is wired to its own field with aria-describedby, and the field carries aria-invalid.
• Give the form an aria-label where the page holds more than one.