The structure that turns individual inputs into a task a user can complete: grouped fields, clear labels, useful helper text, recoverable validation, and actions that match the user's progress.
Form layout starts once individual controls need to work together as one task. Use it to make field order, grouping, validation, and actions predictable.
A form layout owns the composition around field primitives: order, grouping, validation recovery, and action placement.
A heading that names the task, not the database object. Use "New vendor request," not "Vendor form."
Use a real heading and keep it aligned with the route or panel title.
Use sections when a form has multiple groups of fields. The section heading names the decision the group supports.
Do not add section wrappers around short forms that already scan cleanly.
Every input has a visible, persistent label. Placeholder text is not a label.
Connect label and control with the component API or native htmlFor/id wiring.
Helper text explains why or how to answer before submission. Error text explains what to fix after validation.
Use aria-describedby for helper and error text, and aria-invalid when a field is invalid.
Primary and secondary actions sit after the fields. The primary action names the outcome: "Save vendor," "Submit request," "Send invite."
Do not silently disable the primary action; explain missing requirements inline.
Pick the layout by task complexity. A short settings form, a grouped request, and a final review state need different structure.
One short task where every field belongs to the same idea.
Trigger: A settings edit, profile update, or small create flow with roughly three to seven fields.
Job: Keep the form compact, ordered, and easy to complete without extra section framing.
A longer form split into sections that match the user's mental model.
Trigger: A create or edit flow where fields naturally cluster by business details, contact details, permissions, or settings.
Job: Make a longer form scannable without hiding fields behind unnecessary steps.
A form state that helps users check important entries before final submission.
Trigger: A consequential request, compliance workflow, or irreversible submission.
Job: Show the most important entered values, surface unresolved validation, and keep the final action explicit.
The rendered examples use existing form primitives. The pattern is the arrangement around them, not a new component.
Vendor details
Use one section when all fields answer the same question.
Use the name shown on tax documents.
Choose the closest category.
We use this for compliance reminders.
New vendor request
Group fields by the decision they support.
Vendor review
Show the entries that matter before the final submit action.
Add this before submitting.
Primary action on an incomplete form
Submit
The button is disabled until every required field is complete.
Submit request
If required fields are missing, keep the user in the form and show exactly what needs attention.
Submit requestA disabled button hides the path forward. A clear submit action plus field-level recovery tells the user what happened and what to fix.
Long vendor request form
Vendor information
All fields are stacked in one uninterrupted list.
New vendor request
Fields are grouped into Business details and Primary contact so the user can scan the task in chunks.
Submit requestGrouping by decision makes a longer form easier to scan without turning it into an unnecessary wizard.
Labels, helper text, errors, and action labels carry the user through the form.
Labels should name the information requested: "Primary contact email," not "Enter email."
Helper text earns its space when it reduces uncertainty. Do not repeat the label or state the obvious.
Tell the user what to fix and where. "Enter a valid email address" beats "Invalid input."
"Submit request" or "Save vendor" beats "Submit." The action label should match what happens next.
Form accessibility depends on wiring the group, label, description, error, and focus behavior together.
Labels remain visible when a field has a value. Placeholder-only forms fail this rule.
Use fieldset and legend for radio or checkbox groups when the group label is needed to understand the options.
Helper text and error text must be connected with aria-describedby. Invalid fields set aria-invalid.
If the user submits with errors, move focus to an error summary or the first invalid field and preserve entered values.
Field primitives own control behavior. The pattern owns composition and review quality.
Field primitives own labels, helper text, error text, and control states. The pattern owns ordering, grouping, section spacing, and action placement.
Use this as the acceptance gate before approving a form layout.
