FormGroup
Form groups collect related controls with fieldset semantics, optional context, and stack or inline layout.
Overview and decision boundary
Use FormGroup to group related fields or controls with a semantic title, optional description, optional message, and stack, inline, or responsive grid layout.
Do not add form submission, validation-library integration, or schema behavior to FormGroup.
Preview
import { Field, FormGroup } from '@nerio-ui/ui';import { Checkbox } from '@nerio-ui/ui/client';<FormGroup layout="grid" title="Notifications" description="Choose which updates should be sent by email."> <Field label="Product updates"><Checkbox aria-label="Product updates" /></Field> <Field label="Security alerts"><Checkbox aria-label="Security alerts" defaultChecked /></Field></FormGroup>Installation and imports
Install the editable registry source, or use the matching package entrypoint when the product keeps Nerio as a workspace dependency.
pnpm dlx nerio add form-groupimport { Field, FormGroup } from '@nerio-ui/ui';import { Checkbox } from '@nerio-ui/ui/client';Usage
import { Field, FormGroup } from '@nerio-ui/ui';import { Checkbox } from '@nerio-ui/ui/client';<FormGroup layout="grid" title="Notifications" description="Choose which updates should be sent by email."> <Field label="Product updates"><Checkbox aria-label="Product updates" /></Field> <Field label="Security alerts"><Checkbox aria-label="Security alerts" defaultChecked /></Field></FormGroup>Variants
| Variant | Purpose |
|---|---|
stack | Stack is part of the public component contract. |
inline | Inline is part of the public component contract. |
grid | Grid is part of the public component contract. |
invalid | Invalid is part of the public component contract. |
Anatomy
| Slot | Purpose |
|---|---|
root | Server-safe fieldset wrapper. |
title | Legend text that names the group. |
description | Optional supporting text connected by aria-describedby. |
content | Native children composition for Field, Checkbox, Switch, or custom controls. |
message | Optional group-level help or validation message. |
States
| State | Purpose |
|---|---|
Default | Groups related controls without owning validation logic. |
Invalid | Exposes aria-invalid and uses alert semantics only for active invalid messages. |
Motion
- State changes should use shared motion tokens and preserve reduced-motion behavior.
Accessibility
- Renders a fieldset and uses legend when title is supplied.
- Associates description and message text through aria-describedby.
- Invalid state is explicit through invalid or aria-invalid and does not own validation logic.
- Validation messages use role="alert" only when invalid is true.
- Does not force a single control pattern or add form submission behavior.
API
| Prop | Purpose |
|---|---|
title / description / message | Optional group text slots. |
layout | stack, inline, or responsive grid. |
invalid | Sets data-invalid, aria-invalid, and alert semantics for message. |
className | Extends the fieldset root. |
Implementation contract
| Contract | Value |
|---|---|
Registry item | form-group installs 5 source files into the configured components directory. |
Base UI | No interactive primitive required. |
Registry dependencies | form-message |
Package dependencies | clsx, react, tailwind-merge, tailwindcss |
Styling contract
| Contract | Value |
|---|---|
Authoring | Complete, statically detectable Tailwind CSS v4 recipes own component visuals. |
Values | Semantic and component --n-* variables remain the canonical customization layer. |
Overrides | Customizable slots merge consumer className values with tailwindCn so conflicting utilities resolve deterministically. |
Residual CSS | Only shared keyframes and scoped no-Preflight compatibility rules remain; there is no parallel visual selector layer. |
Design notes
- Use FormGroup to group related fields or controls with a semantic title, optional description, optional message, and stack, inline, or responsive grid layout.
Do / do not
Do
Use for related notification preferences, radio-like sections, and field clusters.
Do not
Do not add form submission, validation-library integration, or schema behavior to FormGroup.
Related components
Tokens
These are the primary customization points. Override semantic or component tokens instead of changing component source.
| Token | Purpose |
|---|---|
--n-form-group-gap | Public customization point for this component contract. |
--n-form-group-inline-gap | Public customization point for this component contract. |
--n-form-group-title-color | Public customization point for this component contract. |
--n-form-group-description-color | Public customization point for this component contract. |
--n-form-group-message-color | Public customization point for this component contract. |
--n-field-gap | Public customization point for this component contract. |
--n-color-text-primary | Public customization point for this component contract. |
--n-color-text-tertiary | Public customization point for this component contract. |
--n-color-status-danger | Public customization point for this component contract. |