Form
A layout shell for a set of fields: one vertical rhythm, an actions row, and a fixed place for the submit result.
Installation
npx shadcn@latest add @flyingsalmon/formUsage
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.
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.
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’tLock 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.
- DoShow 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.
- DoWhen 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
| Key | Description |
|---|---|
| Tab | Moves through the fields and buttons in document order. Form adds nothing to it. |
| Enter | In 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.
| Prop | Type | Default | Description |
|---|---|---|---|
| result | ReactNode | – | Renders below the actions row, as the last child. Pass an Alert; the app picks the variant. |
| noValidate | boolean | true | Turns 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.