suaveplan/packages/ui/react/react-ui/src/components/field-group/field-group.md

FieldGroup

(no submodules)

- field-group.variants — `fieldGroupVariants` is the……

• field-group.variants — fieldGroupVariants is the cva (class-variance-authority) configuration powering every <FieldGroup> render. It is sp…

• field-group.variants — fieldGroupVariants is the……

• field-group.variants — fieldGroupVariants is the cva (class-variance-authority) configuration powering every <FieldGroup> render. It is sp…

• field-group.variants — fieldGroupVariants is the……

• field-group.variants — fieldGroupVariants is the cva (class-variance-authority) configuration powering every <FieldGroup> render. It is sp…

• field-group.variants — fieldGroupVariants is the…

• field-group.variants — fieldGroupVariants is the cva (class-variance-authority) configuration powering every <FieldGroup> render. It is sp…

• field-group.variants — fieldGroupVariants is the cva (class-variance-authority) configuration powering every <FieldGroup> render. It is sp…

Purpose

<FieldGroup> is the chassis vertical-stack container for <Field> instances. It renders a <div> with flex flex-col gap-* so siblings flow in document order regardless of writing direction (RTL / LTR). Per the shadcn skill rule the chassis NEVER uses space-y-* because it collapses cross-axis margin in unpredictable ways under RTL.

Per the cross-cutting reconciliation note (#1), shadcn ships field-group as a separate registry item from field; this package mirrors that split so each primitive evolves independently. <FieldGroup> is the typical container for CRUD forms — multiple <Field> instances stacked with a uniform gap.

The gap axis lets consumers tune spacing without reaching for arbitrary Tailwind classes: sm (8px) for dense settings panes, default (16px) for typical CRUD forms, lg (24px) for sectioned profile pages.

Features

• Three gap sizes (sm → gap-2, default → gap-4, lg → gap-6).
• flex flex-col layout so siblings stack in document order under both LTR and RTL.
• Native HTML attributes forwarded — consumers drop role="group" aria-labelledby="…" for accessible grouping.
• Refs forwarded to the underlying <div>.
• Theme-driven variant overrides via useThemedVariants("FieldGroup", fieldGroupVariants).
• NEVER uses space-y-* per the shadcn skill rule.

Usage: Basic Example

import { FieldGroup, Field, FieldLabel, Input } from "@suaveplan/react-ui";

export function ContactForm() {
    return (
        <FieldGroup>
            <Field>
                <FieldLabel htmlFor="email">Email</FieldLabel>
                <Input id="email" type="email" />
            </Field>
            <Field>
                <FieldLabel htmlFor="phone">Phone</FieldLabel>
                <Input id="phone" type="tel" />
            </Field>
        </FieldGroup>
    );
}

Usage: Advanced Example

import {
    FieldGroup,
    Field,
    FieldLabel,
    FieldDescription,
    Input,
} from "@suaveplan/react-ui";

export function ProfileSection() {
    return (
        <section aria-labelledby="profile-h">
            <h2 id="profile-h">Profile</h2>
            <FieldGroup gap="lg" role="group" aria-labelledby="profile-h">
                <Field>
                    <FieldLabel htmlFor="display-name">Display name</FieldLabel>
                    <Input id="display-name" />
                    <FieldDescription>Visible to other users.</FieldDescription>
                </Field>
                <Field>
                    <FieldLabel htmlFor="bio">Biography</FieldLabel>
                    <Input id="bio" />
                </Field>
                <Field>
                    <FieldLabel htmlFor="website">Website</FieldLabel>
                    <Input id="website" type="url" />
                </Field>
            </FieldGroup>
        </section>
    );
}

API Reference

<FieldGroup>

forwardRef<HTMLDivElement, FieldGroupProps> — renders a <div> container.

FieldGroupProps

Prop	Type	Default	Description
gap	"sm" | "default" | "lg"	"default"	Spacing between sibling <Field> instances.
all native HTMLAttributes<HTMLDivElement>	native	native	Forwarded as-is.

fieldGroupVariants

The bare cva resolver. Exported so external consumers can re-use the variants directly.

Implementation Notes

• The container is intentionally minimal — layout (flex flex-col), gap, and forwarded native attrs only. Consumers that need an explicit ARIA grouping role pass role="group" + aria-labelledby themselves.
• Per the shadcn skill rule, the cva NEVER uses space-y-* — gap-* flows the same in RTL and consumer-applied flex utilities stack predictably.
• Per the cross-cutting reconciliation note (#1), this is a separate registry item from field. Keeping them split lets a consumer eject only field if they want to compose their own group container.
• Refs target the <div> — consumers can measure or scroll-into-view the group programmatically.
• The gap axis maps directly to Tailwind's gap scale; consumers wanting an arbitrary gap pass className="gap-3" (Tailwind class merging via tailwind-merge resolves the conflict against the cva default).