FormSection
<FormSection> groups related form fields under a heading. Drop two or three sections inside a long form to give the user a mental map.
When to use
- Long forms (≥ 6 fields) where related fields cluster naturally (“Basic info”, “Visibility”, “Advanced”).
- Settings pages where each section maps to a sub-feature.
Don’t use FormSection for: a 2–3 field form (just stack the fields), a section that has no shared theme (just a divider then), or as a styled container — it’s structural, not decorative.
Default
Basic info
The minimum required to create the agent.<FormSection title="Basic info" description="The minimum required to create the agent."> <div className="space-y-1.5"> <Label>Name</Label> <Input placeholder="Acme Corp" /> </div> <div className="space-y-1.5"> <Label>Description</Label> <Textarea placeholder="What does this agent do?" /> </div></FormSection>API
| Prop | Type | Default | Description |
|---|---|---|---|
title | string | — | Renders as <H3>. Sentence case. |
description | string | — | Optional helper paragraph below the title. |
children * | ReactNode | — | Form fields. The wrapper applies space-y-4. |
className | string | — | Forwarded. |
Design guidelines
✓ Do
- Cluster fields by user's mental model — "Basic info" first, then "Visibility", then "Advanced".
- Keep sections short — 3–6 fields each. Long sections defeat the point.
- Pair with PageContent narrow or SplitContent for the form column width.
✗ Don't
- Use FormSection for a single field. It will look stranded.
- Add custom borders or background colors. The visual hierarchy comes from the heading + spacing alone.
- Nest FormSection. If the form is that long, consider a Stepper.
Accessibility
- Title renders as
<H3>— the section is announced via heading nav. - Description is a
<p>styled muted; it isn’t auto-linked to fields. For per-field hints use<FormDescription>.
Related
Form— Wrapper that provides the validation context.PageContent— Form-page layout.