Skip to content
flyingsalmon

Form

A layout shell for a set of fields: one vertical rhythm, an actions row, and a fixed place for the submit result.

mmddyyyy
mmddyyyy

Installation

npx shadcn@latest add @flyingsalmon/form

Usage

import { Button } from '@/components/ui/button'
import { Form, FormActions } from '@/components/ui/form'
import { Input } from '@/components/ui/input'

export function FormUsage({ onSave }: { onSave: (tripName: string) => void }) {
  function saveTrip(event: React.FormEvent<HTMLFormElement>) {
    event.preventDefault()
    onSave(String(new FormData(event.currentTarget).get('tripName')))
  }

  return (
    <Form onSubmit={saveTrip}>
      <Input label="Trip name" name="tripName" />
      <FormActions>
        <Button type="submit">Save trip</Button>
      </FormActions>
    </Form>
  )
}

Examples

Live submit

Press Save trip. The button morphs into its loading state, the fields stay editable while the request runs, and the result lands in the slot below the actions.

Field errors

Each field owns its failure: the label, the border, the ring, and the message. Form neither collects them nor renders a summary.

Enter a valid email address

Say a little more than that

A server error in the result slot

This demo's server is offline. A failure that belongs to the whole form goes through the same slot as a success, and the typed values stay where they are.

Every field in one form

Input, combobox, date picker, number field, select, radio group, toggle group, slider, textarea, switch, and checkbox share one rhythm, and a plain submit posts them all by name.

mmddyyyy
mmddyyyy
Stays
Interests
Pace, from relaxed to packed

Guidelines

When to use

  • To lay out two or more fields with an actions row, on a page or in a card.
  • In a dialog body, where the dialog owns the footer, closes on submit, and leaves the result to the changed item.

When not to use

  • Use Input for a single field with no submit step, such as a search box. Put the field on the page directly.

Do and don’t

  • Don’t
    Lock the fields while the form submits.Only the submit button shows busyness. The fields stay editable, so a typo can be fixed while the request runs.
  • Do
    Show a failure or success of the whole form below the actions row, and a failure of one field on that field.The whole-form result appears under the button the traveller just pressed, so their attention is already there and the button never moves. A field failure points at exactly what to fix.
  • Do
    When the submit cannot run yet, say why in a muted line beside it in the actions row, such as "3 questions left".The traveller reads the reason where they reached for the action, and knows what to answer next.

Accessibility

KeyDescription
TabMoves through the fields and buttons in document order. Form adds nothing to it.
EnterIn a text field, submits through native implicit submission. In a textarea, inserts a newline.

Form sets noValidate by default, and you can override it. The field’s error string is the one error channel: native constraint validation would add a second, a browser bubble placed by the user agent, unowned and gone on the next click.

Form has no Cmd or Ctrl+Enter shortcut. A hidden keybinding with no visible affordance only helps people who already guess it exists, and Tab then Enter on the submit button already works. The result slot carries no live region of its own: the alert you pass announces itself through its role. For the states every field shares, see Fields.

API

Form

Renders a real <form> and takes its attributes, so onSubmit, action, method, and id behave as they do on the element. Every field already owns its label, id linkage, and error message, so fields go in as plain children with no wrapper.

PropTypeDefaultDescription
resultReactNode–Renders below the actions row, as the last child. Pass an Alert; the app picks the variant.
noValidatebooleantrueTurns off native constraint bubbles so a field’s error is the one error channel.

FormActions takes the props of a <div>, typed as FormActionsProps. It stacks its buttons full width on a narrow screen and lays them out in a right-aligned row on a wider one. It is optional: a one-button form can put the button in directly. FormActions injects nothing into its children, so write type="submit" on the one button that submits and set its loading while the request runs. Button defaults to type="button", so a Cancel beside it never posts the form.

  • Button

    The submit button and its loading state.
  • Alert

    What you pass to the result slot.
  • Dialog

    Hosts a form in a modal that closes on submit.
  • Fields

    The label, description, error, loading, and disabled behaviour every field shares.
  • Principles

    Where a result belongs, and why nothing auto-dismisses.