Groups & layout
Recursive groups, grid vs stack layouts, and group-level behavior.
Groups are recursive containers. They organize questions visually and act as a unit for conditional logic.
Shape
interface Group<TFormData> {
id?: string; // required when the group has `dependents`
title?: string;
description?: string;
className?: string;
layout?: 'stack' | 'grid';
gridCols?: 1 | 2 | 3 | 4 | 6 | 12;
dependents?: Dependency<TFormData>;
clearWhenHidden?: boolean;
questions?: Question<TFormData>[];
groups?: Group<TFormData>[]; // nest groups arbitrarily deep
}Grid vs stack
The default layout is stack (one field per row). Use grid with gridCols to place
fields side by side.
Grid class goes on the inner content div
When you build a custom group renderer, put the grid class on the inner content
<div>, not the <section>. Otherwise the group title becomes the first grid cell and
every field misaligns.
Group-level conditional logic
A group can declare dependents to hide or relabel the whole section at once. A group with
dependents must have a stable id — the dependency engine uses it as the group's
address in the graph.
When a group is hidden, it is CSS-hidden (not unmounted), so descendant field state is
preserved across show/hide. Hidden descendants drop out of getValues() and skip
validation. Set clearWhenHidden to reset descendants when the group hides.
See Conditional groups for a live example.