Layout container for a set of fields. The smallest component in the form/table primitive set and the one that decides whether QDS forms look like one system.
The qds-form-grid component provides a CSS Grid layout for grouping form fields. It reads column spans from a data-span attribute on its light-DOM children, supports container-driven responsive collapsing, and cascades label-orientation and dense attributes to its slotted children.
CLAUDE.md says to use PrimeFlex classes where appropriate. PrimeFlex classes cannot cross a shadow boundary: a p-col-6 on a slotted child is styled by the page’s stylesheet, but the grid container inside this component’s shadow root cannot see or coordinate with it. So this component implements its own CSS Grid and reads column spans from a data-span attribute on its light-DOM children. The alternative — making qds-form-grid a light-DOM component with no shadow root — would let PrimeFlex work but breaks the pattern every other QDS component follows.
data-span contractSlotted children control their column span via a data-span attribute:
data-span — the child occupies one column (default).data-span="N" (a number 1-N) — the child spans N columns. Values above columns clamp to columns.data-span="full" — the child spans all columns (equivalent to grid-column: 1 / -1).Section headings are plain slotted content with data-span="full" — a <h3 data-span="full"> works. No separate qds-form-grid-section element is needed.
When the container collapses to fewer columns (via @container queries), data-span values are clamped to the current column count by CSS, so a data-span="2" field still spans the full width when the grid has collapsed to one column.
<qds-form-grid columns="2" gap="md">
<qds-field label="Account name"><qds-text-input></qds-text-input></qds-field>
<qds-field label="Account code"><qds-text-input></qds-text-input></qds-field>
<qds-field label="Description" data-span="2"><qds-text-input></qds-text-input></qds-field>
</qds-form-grid>
columns - 1 | 2 | 3 | 4. Maximum columns at the widest breakpoint. Default 1.gap - sm | md | lg. Row and column gap. Default md.row-gap - sm | md | lg. Overrides the row gap only. Defaults to gap.label-orientation - vertical | horizontal. Pushed to every slotted qds-field. Default vertical.dense - boolean. Sets size="sm" on slotted fields and field-consumer controls.gap |
Column gap | Row gap |
|---|---|---|
sm |
--theme-space-3 (12px) |
--theme-space-3 (12px) |
md |
--theme-space-6 (24px) |
--theme-space-4 (16px) |
lg |
--theme-space-10 (40px) |
--theme-space-6 (24px) |
Column gaps are wider than row gaps at every step. Two adjacent fields need enough horizontal separation that the eye does not read them as one wide field; vertically, labels already separate them.
grid - The CSS Grid container.--qds-form-grid-columns - Derived from columns. Read-only; use the attribute to change.--qds-form-grid-column-gap - Derived from gap. Read-only; use the attribute to change.--qds-form-grid-row-gap - Derived from row-gap or gap. Read-only; use the attribute to change.--qds-form-grid-min-column - 240px. Minimum column width before collapsing. Consumer-overridable.This component dispatches no custom events. It is a presentational layout container.
Container-driven, not viewport-driven — a form inside a 400px panel collapses regardless of window width.
| Container width | Columns |
|---|---|
< 480px |
1 |
480-767px |
min(2, columns) |
768-1023px |
min(3, columns) |
>= 1024px |
columns |
The grid is presentational: no role, no ARIA. It must not introduce a role="group" — grouping semantics belong to a <fieldset> the author supplies. Source order is DOM order; the grid never visually reorders children.
<qds-form-grid columns="3" gap="lg">
<h3 data-span="full">Account Details</h3>
<qds-field label="Name"><qds-text-input></qds-text-input></qds-field>
<qds-field label="Code"><qds-text-input></qds-text-input></qds-field>
<qds-field label="Type">
<qds-select></qds-select>
</qds-field>
<qds-field label="Description" data-span="full">
<qds-text-input></qds-text-input>
</qds-field>
</qds-form-grid>