Form
<forma-form>
A semantic, responsive native form contract with aligned fields, explicit submit/reset commands, native validation and observable script-free feedback.
- Authoring tag
<forma-form>- Category
- Form inputs
- Behavior owner
- Native HTML
- Canonical source
patterns/form.html
Purpose
Form is the end-to-end composition for collecting and submitting related data. It combines Form row, Text field, Select, Textarea, Checkbox, Choice group, Switch, Date and time field, Validation message and Button without replacing their native semantics. The optional Forma design contract validates this structure before rendering; hand-authored HTML remains equally supported.
Use when
- A page or region collects related values and has a real submit command.
- Peer fields need aligned controls on wide containers and source-order stacking on narrow containers.
- Native constraint validation and reset behavior are sufficient, or an application will add richer behavior through Limen.
Avoid when
- A single value saves immediately on change: use its native control and application feedback without inventing a form action row.
- The surface only navigates or runs commands and collects no data: use Button, links, or a command pattern.
- Domain legality or asynchronous persistence is being encoded in CSS: keep those decisions in the application or Limen.
Behavior to know
- The form is a min-width-zero grid with semantic spacing and an optional maximum measure.
.forma-form-rowaligns label, description, control and validation tracks and wraps by container width.- A successful GET submit can target
.forma-form__outcome; invalid native controls refuse submission first. - No form interaction requires Forma JavaScript.
Basic example
The smallest correct markup: the canonical pattern from patterns/form.html inside its public tag. Copy this first, then adapt labels, names and state.
Minimal form
Rendered from the canonical pattern file.
Live demo. 2 native actions work here and are verified by an outcome test.
<forma-form class="forma-component-tag">
<form class="forma-form" id="nasa-mission-customer" method="get" action="#nasa-mission-customer-saved" aria-labelledby="nasa-mission-customer-title">
<h2 id="nasa-mission-customer-title">Artemis mission customer contact</h2>
<div class="forma-form-row" data-forma-form-layout="grid">
<div class="forma-field">
<label class="forma-field__label" for="nasa-mission-contact-name">Mission contact name (required)</label>
<span class="forma-field__description" id="nasa-mission-contact-name-description">Primary contact for Artemis II payload coordination.</span>
<input type="text" id="nasa-mission-contact-name" name="contact-name" required autocomplete="name" value="Reid Wiseman" aria-describedby="nasa-mission-contact-name-description nasa-mission-contact-name-error">
<p class="forma-validation-message forma-validation-message--when-invalid" id="nasa-mission-contact-name-error"><span class="forma-validation-message__mark" aria-hidden="true">!</span>Enter the mission contact name.</p>
</div>
<div class="forma-field">
<label class="forma-field__label" for="nasa-mission-contact-email">Mission contact email (required)</label>
<span class="forma-field__description" id="nasa-mission-contact-email-description">Use the monitored address for launch-window updates.</span>
<input type="email" id="nasa-mission-contact-email" name="contact-email" required autocomplete="email" inputmode="email" value="artemis-ii@nasa.gov" aria-describedby="nasa-mission-contact-email-description nasa-mission-contact-email-error">
<p class="forma-validation-message forma-validation-message--when-invalid" id="nasa-mission-contact-email-error"><span class="forma-validation-message__mark" aria-hidden="true">!</span>Enter an email address such as name@nasa.gov.</p>
</div>
</div>
<div class="forma-actions"><button type="submit">Save customer</button><button type="reset">Reset form</button></div>
<p class="forma-form__outcome" id="nasa-mission-customer-saved" role="status" aria-label="Save status">Mission customer contact saved.</p>
</form>
</forma-form>
Click or tap the code once to select all of it, then copy.
Examples
Orion communications handoff
An advanced form combines aligned native controls, a select, date field, textarea and required checkbox. Reset restores the mission note; Save submits the complete form to observable feedback.
Live demo. 2 native actions work here and are verified by an outcome test.
<forma-form class="forma-component-tag">
<form class="forma-form" method="get" action="#orion-handoff-saved" aria-labelledby="orion-handoff-title">
<h2 id="orion-handoff-title">Orion communications handoff</h2>
<div class="forma-form-row">
<div class="forma-field">
<label class="forma-field__label" for="orion-network">Network complex (required)</label>
<span class="forma-field__description" id="orion-network-description">Choose the Deep Space Network complex leading the handoff.</span>
<span class="forma-select">
<select class="forma-select__input" id="orion-network" name="network" required aria-describedby="orion-network-description">
<option value="goldstone">Goldstone · California</option>
<option value="madrid">Madrid · Spain</option>
<option value="canberra">Canberra · Australia</option>
</select>
<span class="forma-select__indicator" aria-hidden="true"></span>
</span>
</div>
<div class="forma-field">
<label class="forma-field__label" for="orion-handoff-date">Handoff date (required)</label>
<span class="forma-field__description" id="orion-handoff-date-description">Use the UTC mission-planning date.</span>
<input id="orion-handoff-date" name="handoff-date" type="date" value="2026-04-01" required aria-describedby="orion-handoff-date-description">
</div>
</div>
<div class="forma-field">
<label class="forma-field__label" for="orion-handoff-note">Handoff note</label>
<textarea id="orion-handoff-note" name="handoff-note" rows="3">Confirm Deep Space Network coverage before launch.</textarea>
</div>
<label class="forma-checkbox">
<input class="forma-checkbox__input" type="checkbox" name="flight-director-reviewed" value="yes" required checked>
<span class="forma-checkbox__box" aria-hidden="true"></span>
<span class="forma-checkbox__text"><span class="forma-checkbox__label">Flight director review complete (required)</span></span>
</label>
<div class="forma-actions">
<button type="submit">Save handoff</button>
<button type="reset">Reset handoff</button>
</div>
<p class="forma-form__outcome" id="orion-handoff-saved" role="status" aria-label="Handoff save status">Orion communications handoff saved.</p>
</form>
</forma-form>
Click or tap the code once to select all of it, then copy.
Submission pending
After a valid submit the application marks the form aria-busy="true", wraps its fields in <fieldset disabled> so the browser refuses edits and a second submission, and marks the submit button pending. A status message names the work. When the save completes or fails, the application removes all three and reports the outcome.
Static specimen. Its buttons stand for application actions that the consuming application implements; this script-free documentation does not perform them. Its controls are shown for their markup and appearance and cannot be operated here.
<forma-form class="forma-component-tag">
<form class="forma-form" action="#" method="post" aria-busy="true" aria-describedby="form-pending-status">
<fieldset disabled>
<legend>Crew contact</legend>
<div class="forma-field">
<label class="forma-field__label" for="form-pending-name">Contact name</label>
<input id="form-pending-name" name="contact" type="text" value="Mae Jemison" autocomplete="name">
</div>
<div class="forma-actions">
<button type="submit" aria-busy="true" aria-disabled="true">Saving contact</button>
</div>
</fieldset>
<p id="form-pending-status" role="status">Saving the crew contact.</p>
</form>
</forma-form>
Click or tap the code once to select all of it, then copy.
Customer email validation
A compact customer form uses native required and email constraints. The linked recovery message appears when the browser refuses an invalid submission; valid Save and Reset actions remain native.
Live demo. 2 native actions work here and are verified by an outcome test.
<forma-form class="forma-component-tag">
<form class="forma-form" method="get" action="#gateway-contact-saved" aria-labelledby="gateway-contact-title">
<h2 id="gateway-contact-title">Gateway logistics contact</h2>
<div class="forma-field">
<label class="forma-field__label" for="gateway-contact-email">Customer email (required)</label>
<span class="forma-field__description" id="gateway-contact-email-description">Receives lunar logistics schedule changes.</span>
<input id="gateway-contact-email" name="email" type="email" value="gateway@nasa.gov" autocomplete="email" required aria-describedby="gateway-contact-email-description gateway-contact-email-error">
<p class="forma-validation-message forma-validation-message--when-invalid" id="gateway-contact-email-error"><span class="forma-validation-message__mark" aria-hidden="true">!</span>Enter an email address such as name@nasa.gov.</p>
</div>
<div class="forma-actions">
<button type="submit">Save contact</button>
<button type="reset">Reset contact</button>
</div>
<p class="forma-form__outcome" id="gateway-contact-saved" role="status" aria-label="Contact save status">Gateway logistics contact saved.</p>
</form>
</forma-form>
Click or tap the code once to select all of it, then copy.
Mobile
Each mobile example renders in its own document inside a real narrow viewport, so Forma's media and container queries run exactly as they would on a phone. Choose a width to compare.
Mobile mission customer
The same two-field contract at phone width. Fields stack in source order, labels and validation wrap, and both actions remain reachable without horizontal page scrolling.
Live demo. 2 native actions work here and are verified by an outcome test.
What changes at narrow widths
- The auto-fit form row becomes one column from available container width, not device detection.
- Controls and actions keep at least 44px target height and fill or wrap within 320px.
- DOM, reading, focus, validation and submission order remain name then email then actions.
- The form adds no motion; reduced-motion mode preserves identical state and behavior.
<forma-form class="forma-component-tag">
<form class="forma-form" method="get" action="#mobile-mission-customer-saved" aria-labelledby="mobile-mission-customer-title">
<h2 id="mobile-mission-customer-title">Mission customer</h2>
<div class="forma-form-row">
<div class="forma-field">
<label class="forma-field__label" for="mobile-mission-customer-name">Mission customer name (required)</label>
<input id="mobile-mission-customer-name" name="name" type="text" value="Artemis II" autocomplete="organization" required>
</div>
<div class="forma-field">
<label class="forma-field__label" for="mobile-mission-customer-email">Mission customer email (required)</label>
<span class="forma-field__description" id="mobile-mission-customer-email-description">Monitored during launch-window operations.</span>
<input id="mobile-mission-customer-email" name="email" type="email" value="artemis-ii@nasa.gov" autocomplete="email" required aria-describedby="mobile-mission-customer-email-description">
</div>
</div>
<div class="forma-actions">
<button type="submit">Save mobile customer</button>
<button type="reset">Reset mobile form</button>
</div>
<p class="forma-form__outcome" id="mobile-mission-customer-saved" role="status" aria-label="Mobile save status">Mission customer saved.</p>
</form>
</forma-form>
Click or tap the code once to select all of it, then copy.
Mobile · 320px
The canonical pattern in a true 320px viewport, the minimum width every Forma component must support without page-level horizontal scrolling.
Live demo. 2 native actions work here and are verified by an outcome test.
API and configuration
Forma components have no JavaScript API. Their public contract is the markup: native elements and attributes you write, and the CSS hooks below. The CSS hook table is generated from the built stylesheet, so it always matches the shipped implementation.
| Attribute | On | Values | Default | Description |
|---|---|---|---|---|
method | form.forma-form | get | post | get | Native form submission method. Static documentation uses GET so its result is observable in the URL. |
action | form.forma-form | URL or #feedback-id | current URL | Real submission destination. A local fragment may expose .forma-form__outcome; production persistence belongs to the application endpoint. |
type | button | submit | reset | button | submit | Write the native command explicitly. Design-contract standard mode binds submit and reset only. |
required | native form control | boolean | absent | Participates in native constraint validation. Also state required status in visible text. |
aria-describedby | native form control | description and validation ids | — | Associates guidance and recovery text in reading order. |
role | .forma-form__outcome | status | — | Announces newly navigated save feedback without moving focus. |
aria-busy | form.forma-form | true | absent | Marks a submission in flight: progress cursor on the form. Pair it with <fieldset disabled> around the fields (the browser then refuses edits and resubmission) and a pending submit button; the application removes all three when the work finishes. |
| Hook | Kind | Values or default | Description |
|---|---|---|---|
.forma-form | Block class | — | Form root: a min-width-zero grid with semantic vertical spacing, container context and an optional maximum measure. |
.forma-form__outcome | Element class | — | Native fragment-targeted status. Hidden until it is the current URL target, then shown with a non-colour border cue. |
[aria-busy] | Attribute hook | "true" | Pending selector: .forma-form[aria-busy="true"] sets the progress cursor; the disabled fieldset does the rest natively. |
--forma-form-gap | Custom property | — | Space between heading, field layouts, action group and feedback. |
--forma-form-max | Custom property | — | Maximum inline measure of the form; defaults to 64rem. |
| Keys | Result |
|---|---|
| Tab / Shift+Tab | Moves through native controls and actions in DOM order. |
| Enter | In a single-line field, invokes the form's default submit action when constraints pass. |
| Space or Enter | Activates the focused Save or Reset button through native button behavior. |
| Event | Description |
|---|---|
submit | Native form event after successful constraint validation. |
reset | Native form event when initial control values are restored. |
invalid | Native event on each control that blocks submission. |
Form behavior
Native form participation is the contract. Submit includes successful named controls, reset restores initial values, disabled controls are omitted, readonly controls are included, and invalid required/type constraints refuse submit.
States
| State | How it is expressed | Presentation |
|---|---|---|
| Ready | valid native controls | Save can submit; Reset restores declared initial values. |
| Invalid | :user-invalid plus linked .forma-validation-message--when-invalid | Submission is refused; a thicker danger-side border and text recovery message identify the field without colour alone. |
| Saved | .forma-form__outcome:target | A successful native GET reaches the declared URL fragment and exposes status feedback. |
| Pending | aria-busy="true" on the form, fields inside <fieldset disabled>, pending submit button | The browser refuses edits and resubmission through the disabled fieldset; the form shows a progress cursor and its status message names the work. The application restores the form and reports success or failure. |
| Disabled or read-only field | disabled or readonly native attribute | Disabled controls are dashed, dimmed and omitted from submission; read-only text controls are dashed and remain focusable, selectable and submitted. |
Accessibility
Forma provides
- Native form, label, input, select, textarea, fieldset and button semantics with visible focus and 44px control/action heights.
- Grid fields preserve semantic and focus order when they wrap; validation text is programmatically associated.
- Invalid state uses border shape plus marked text, saved state uses status text, and forced colours retain system borders.
- No form motion is required, so reduced motion changes no meaning or reachability.
Your application supplies
- Supply unique ids, names, visible labels, correct input types/autocomplete and actionable validation messages.
- Provide a real application endpoint or Limen handler for persistence; never ship a decorative Save button.
- For several errors, build and focus a Validation summary after submit while retaining field values.
- Keep authorization and domain legality outside the design contract.
Responsive behavior
- The form and every field have min-inline-size: 0 and max-inline-size constraints, preventing intrinsic controls from widening the page.
.forma-form-rowuses auto-fit minmax columns; it stacks at narrow container widths without media-query device guesses.- Labels, descriptions, messages and actions wrap; native select display text may ellipsize inside its bounded control while the full option remains available.
- At 320px all controls and actions stay reachable with no page-level horizontal overflow.
Motion
- Form layout, validity, submit, reset and target feedback introduce no animation.
- Controls reused inside the form follow their documented motion models; global reduced-motion rules shorten or remove nonessential transitions without changing state.
Usage guidance
Do
- Use one clear heading, group peer fields in
.forma-form-row, and keep DOM order equal to reading and keyboard order. - Use explicit native button types and make every enabled action produce its declared result.
- Validate with the versioned design contract when UI is generated by agents or authoring tools.
Avoid
- Local margins that nudge one field into alignment, raw positioning overrides, or nowrap content that widens the page.
- Placeholder-only labels, hidden required state, colour-only error borders, and Save buttons without a command binding.
- Treating successful contract validation as proof of domain correctness or visual quality.
Verification specimens
Generated fault-injection specimens expose content, spacing, color-cue, and reduced-effective-contrast risks. They screen presentation robustness as engineering screens without claiming human-subject validation.