VERIFICATION-0123456789ABCDEF0123456789ABCDEF0123456789ABCDEF
Form row
<forma-form-row>
Peer form fields side by side whose controls share one top edge however long their labels, descriptions or validation messages are; fields wrap to new rows by available width.
- Authoring tag
<forma-form-row>- Category
- Layout primitives
- Behavior owner
- Native HTML
- Canonical source
patterns/form-row.html
Purpose
A form row places related Text field, Select and Date and time field fields side by side and keeps their controls aligned. Every .forma-field in the row spans the same four subgrid rows: label, description, control and validation message. A field without a description or message leaves its row empty, so its control still starts on the same line as its peers' controls (visual-engineering/UI-LAYOUT-INTERACTION@1.0.0 ULI-L01). Columns are as wide as --forma-form-row-min allows and wrap into new rows on narrow screens. Use it instead of a generic Grid whenever the children are fields, and instead of local margins that nudge one control into line (ULI-L13).
Use when
- Two or more short, related fields belong on one line: given and family name, date and time, quantity and unit, city and postal code.
- Peer fields have different label lengths, a description on only some of them, or a validation message that appears on one of them.
- A form must keep one column on phones and several columns on wider screens without a breakpoint.
Avoid when
- The fields are not peers, or the reading order would be unclear side by side: use a single-column Stack.
- The children are cards, summaries or other non-field content: use Grid or Responsive grid.
- A field needs a different layout of its own parts (an inline unit, a button beside the input): wrap those parts in one container element so the field keeps a single control row.
Behavior to know
- Each direct
.forma-fieldchild spans four subgrid rows; its label, description, control and.forma-validation-messageare placed in rows 1 to 4. - Controls in one visual row share their top edge; labels share theirs too.
- Columns are
repeat(auto-fit, minmax(min(100%, var(--forma-form-row-min)), 1fr)); the default minimum is 14rem. - Without subgrid support, each field falls back to its own grid, which is the plain
.forma-fieldlayout.
Basic example
The smallest correct markup: the canonical pattern from patterns/form-row.html inside its public tag. Copy this first, then adapt labels, names and state.
Minimal form row
Rendered from the canonical pattern file.
<forma-form-row class="forma-component-tag">
<div class="forma-form-row">
<div class="forma-field">
<label class="forma-field__label" for="form-row-given-name">Given name</label>
<input id="form-row-given-name" name="given-name" type="text" autocomplete="given-name">
</div>
<div class="forma-field">
<label class="forma-field__label" for="form-row-family-name">Family name</label>
<span class="forma-field__description" id="form-row-family-name-description">As printed on your passport or national identity card.</span>
<input id="form-row-family-name" name="family-name" type="text" autocomplete="family-name" aria-describedby="form-row-family-name-description">
</div>
<div class="forma-field">
<label class="forma-field__label" for="form-row-birth-date">Date of birth</label>
<input id="form-row-birth-date" name="birth-date" type="date" autocomplete="bday">
</div>
</div>
</forma-form-row>
Click or tap the code once to select all of it, then copy.
Examples
Validation message on one field
City and postal code after the application rejected the postal code. The validation message occupies the fourth row of its own field only; the City control stays level with the postal code control, and the message does not push either control down.
<forma-form-row class="forma-component-tag">
<div class="forma-form-row">
<div class="forma-field">
<label class="forma-field__label" for="form-row-error-city">City</label>
<input id="form-row-error-city" name="city" type="text" autocomplete="address-level2" value="Rotterdam">
</div>
<div class="forma-field">
<label class="forma-field__label" for="form-row-error-postal-code">Postal code</label>
<span class="forma-field__description" id="form-row-error-postal-code-description">Four digits and two letters.</span>
<input id="form-row-error-postal-code" name="postal-code" type="text" autocomplete="postal-code" value="30111" aria-invalid="true" aria-describedby="form-row-error-postal-code-description form-row-error-postal-code-error">
<p class="forma-validation-message" id="form-row-error-postal-code-error">
<span class="forma-validation-message__mark" aria-hidden="true">!</span>
Add the two letters, for example 3011 AB.
</p>
</div>
</div>
</forma-form-row>
Click or tap the code once to select all of it, then copy.
Long translated labels
German labels of very different lengths beside a select. The long label wraps onto several lines in its own column; the label row grows for every field in the visual row, so all three controls still start on one line.
<forma-form-row class="forma-component-tag">
<div class="forma-form-row" lang="de">
<div class="forma-field">
<label class="forma-field__label" for="form-row-translated-start">Vertragsbeginn</label>
<input id="form-row-translated-start" name="contract-start" type="date">
</div>
<div class="forma-field">
<label class="forma-field__label" for="form-row-translated-notice">Kündigungsfrist in Monaten nach Ablauf der Mindestvertragslaufzeit</label>
<input id="form-row-translated-notice" name="notice-months" type="number" min="1" max="12" value="3">
</div>
<div class="forma-field">
<label class="forma-field__label" for="form-row-translated-plan">Tarif</label>
<select id="form-row-translated-plan" name="plan">
<option>Basis</option>
<option selected>Plus</option>
<option>Unternehmen</option>
</select>
</div>
</div>
</forma-form-row>
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.
Stacked on a phone
The basic row at phone width. Each field takes the full width in source order; nothing overflows and the label, description and control order is unchanged.
What changes at narrow widths
- Below twice the column minimum the row has one column, so each field is a full-width block in source order.
- Empty description and message rows collapse to nothing, so stacked fields keep the ordinary field spacing.
- Enlarging the text widens the columns' minimum (it is in rem), so the row stacks sooner instead of squeezing the controls.
- There are no breakpoints: the same markup produces one, two or three columns by available width.
<forma-form-row class="forma-component-tag">
<div class="forma-form-row">
<div class="forma-field">
<label class="forma-field__label" for="form-row-mobile-given-name">Given name</label>
<input id="form-row-mobile-given-name" name="given-name" type="text" autocomplete="given-name">
</div>
<div class="forma-field">
<label class="forma-field__label" for="form-row-mobile-family-name">Family name</label>
<span class="forma-field__description" id="form-row-mobile-family-name-description">As printed on your passport or national identity card.</span>
<input id="form-row-mobile-family-name" name="family-name" type="text" autocomplete="family-name" aria-describedby="form-row-mobile-family-name-description">
</div>
</div>
</forma-form-row>
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.
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 |
|---|---|---|---|---|
class="forma-field" | each direct child | — | — | Each peer is an ordinary Text field structure: label, optional description, one control and an optional Validation message. |
for | label.forma-field__label | id of the control | — | Associates the visible label with its control. |
aria-describedby | the control | id list | — | Links the description and, when shown, the validation message, in reading order. |
| Hook | Kind | Values or default | Description |
|---|---|---|---|
.forma-form-row | Block class | — | Grid of peer fields. Columns repeat(auto-fit, minmax(min(100%, var(--forma-form-row-min)), 1fr)); each direct .forma-field spans four subgrid rows (label, description, control, validation message). |
--forma-form-row-gap | Custom property | — | Space between columns and between wrapped rows of fields. Default --forma-primitive-spacing-4 (1rem). |
--forma-form-row-min | Custom property | default 14rem | Minimum column width before fields wrap to a new row. Default 14rem. |
No keyboard interaction beyond the browser defaults for the elements in the markup.
States
| State | How it is expressed | Presentation |
|---|---|---|
| Default | no state attributes | Peer controls share a top edge; empty description or message rows take no space. |
| Field with a validation message | a .forma-validation-message inside one field | The message fills the fourth row of its own field; peers' controls do not move. |
| Wrapped | available width below the column minimum | Fields continue on a new row of the same four-row structure, or stack in one column. |
Accessibility
Forma provides
- Visual order equals source order at every width, so reading and focus order match what is seen.
- Rows never clip or overlap labels; long labels wrap and the row grows.
- Aligned controls make the row easy to scan for people using magnification.
Your application supplies
- Put only genuinely related peers in one row and keep their order logical (for example given name before family name where that is the local convention).
- Give each field a visible label and link descriptions and messages with aria-describedby.
- Keep one control element per field; wrap composite controls in a single container.
Responsive behavior
- Columns wrap by available width with no media queries: three, two or one column from the same markup.
--forma-form-row-minis in rem, so enlarged text stacks the fields sooner instead of shrinking the controls.- Controls keep the shared intrinsic block size of single-line fields at every width.
Motion
- No animation. Showing a validation message grows its own field's fourth row; other fields' controls do not move.
Usage guidance
Do
- Use a form row for short peer fields and a Stack for everything else.
- Write the description or error inside the field it belongs to; the row keeps the controls level.
- Override
--forma-form-row-minon the row when its fields need wider or narrower columns.
Avoid
- Adding top margins or empty description elements to line controls up by hand.
- Putting buttons, headings or non-field content directly in the row.
- Two controls in one field, which would share the control row and overlap.
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.