Group fields
Five layouts for fields that belong together: a row, an asymmetric split, a grid, a titled section and a real fieldset with a legend. Every control keeps its own label association through htmlFor and id, shared help text is wired via aria-describedby, and all ids come from useId so many instances can share a page.
Installation
The styled layer is free and installs like any other ai2 component.
Run the following command
npx shadcn@latest add @ai2/field-groupDependencies, the @ai2/tokens theme and the component file are installed together.
Copy the source
components/ui/field-group.tsx"use client"
import * as React from "react"
import { cn } from "@/lib/utils"
/* Group field family: 5 multi-field form layouts. Not a single control but blocks
where related controls stand together (a side-by-side row, an asymmetric split, a
grid, a titled section, a real fieldset/legend). Every control is matched to its
own label through htmlFor/id, the description is bound with aria-describedby, and
invalidity falls back to the standard danger appearance ON THE CONTROL via
aria-invalid. All ids come from useId, so dozens of examples on the same page do
not collide. Color comes ONLY from tokens. Static - no animation. Renders with no
props too. */
export type StyledSize = "sm" | "md" | "lg" | "xl"
const gap: Record<StyledSize, string> = {
sm: "gap-1",
md: "gap-1.5",
lg: "gap-2",
xl: "gap-2.5",
}
const blockGap: Record<StyledSize, string> = {
sm: "gap-2.5",
md: "gap-3",
lg: "gap-4",
xl: "gap-5",
}
const labelText: Record<StyledSize, string> = {
sm: "text-xs",
md: "text-sm",
lg: "text-sm",
xl: "text-base",
}
const helpText: Record<StyledSize, string> = {
sm: "text-xs",
md: "text-xs",
lg: "text-sm",
xl: "text-sm",
}
const controlHeight: Record<StyledSize, string> = {
sm: "h-8 text-sm",
md: "h-9 text-sm",
lg: "h-10 text-base",
xl: "h-12 text-base",
}
const controlBase =
"w-full rounded-md border border-field-border bg-transparent px-3 py-1 text-foreground outline-none transition-colors placeholder:text-muted-foreground disabled:cursor-not-allowed disabled:opacity-50 focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-ring/50 aria-invalid:border-danger aria-invalid:ring-danger/20 dark:aria-invalid:ring-danger/40"
interface FieldProps {
className?: string
size?: StyledSize
label?: React.ReactNode
description?: React.ReactNode
}
/* Grup icindeki tek bir alan: etiket + kontrol, id eslesmesi burada. */
function SubField({
id,
size,
label,
placeholder,
describedBy,
className,
}: {
id: string
size: StyledSize
label: React.ReactNode
placeholder: string
describedBy?: string
className?: string
}) {
return (
<div className={cn("flex min-w-0 flex-1 flex-col", gap[size], className)}>
<label
htmlFor={id}
data-slot="styled-field-label"
className={cn("w-fit font-medium leading-none text-foreground select-none", labelText[size])}
>
{label}
</label>
<input id={id} placeholder={placeholder} aria-describedby={describedBy} className={cn(controlBase, controlHeight[size])} />
</div>
)
}
function GroupDescription({ id, size, children }: { id?: string; size: StyledSize; children: React.ReactNode }) {
if (children == null || children === false) return null
return (
<p id={id} data-slot="styled-field-description" className={cn("leading-snug text-muted-foreground", helpText[size])}>
{children}
</p>
)
}
/* Row: iki alan yan yana, esit genislikte; ortak aciklama altta. */
export function RowField({
className,
size = "md",
label = "Full name",
description = "As it appears on your ID.",
}: FieldProps) {
const base = React.useId()
const firstId = `${base}-first`
const lastId = `${base}-last`
const descId = description != null && description !== false ? `${base}-desc` : undefined
return (
<div data-slot="styled-field" className={cn("flex w-full max-w-md flex-col", blockGap[size], className)}>
<span className={cn("font-medium leading-none text-foreground", labelText[size])}>{label}</span>
<div className={cn("flex flex-row", blockGap[size])}>
<SubField id={firstId} size={size} label="First" placeholder="Ada" describedBy={descId} />
<SubField id={lastId} size={size} label="Last" placeholder="Lovelace" describedBy={descId} />
</div>
<GroupDescription id={descId} size={size}>
{description}
</GroupDescription>
</div>
)
}
/* Split: asimetrik bolme - genis birincil alan + dar ikincil alan. */
export function SplitField({
className,
size = "md",
label = "Amount",
description = "Enter the amount and pick a currency.",
}: FieldProps) {
const base = React.useId()
const amountId = `${base}-amount`
const currencyId = `${base}-currency`
const descId = description != null && description !== false ? `${base}-desc` : undefined
return (
<div data-slot="styled-field" className={cn("flex w-full max-w-md flex-col", blockGap[size], className)}>
<span className={cn("font-medium leading-none text-foreground", labelText[size])}>{label}</span>
<div className={cn("flex flex-row", blockGap[size])}>
<SubField id={amountId} size={size} label="Value" placeholder="1,250.00" describedBy={descId} className="flex-[2]" />
<div className={cn("flex w-24 shrink-0 flex-col", gap[size])}>
<label
htmlFor={currencyId}
data-slot="styled-field-label"
className={cn("w-fit font-medium leading-none text-foreground select-none", labelText[size])}
>
Currency
</label>
<select
id={currencyId}
aria-describedby={descId}
defaultValue="USD"
className={cn(controlBase, controlHeight[size], "cursor-pointer")}
>
<option value="USD">USD</option>
<option value="EUR">EUR</option>
<option value="TRY">TRY</option>
</select>
</div>
</div>
<GroupDescription id={descId} size={size}>
{description}
</GroupDescription>
</div>
)
}
/* Grid: iki sutunlu izgara, dort alan; dar ekranda tek sutuna duser. */
export function GridField({
className,
size = "md",
label = "Shipping address",
description = "We ship to these details exactly as written.",
}: FieldProps) {
const base = React.useId()
const descId = description != null && description !== false ? `${base}-desc` : undefined
const cells = [
{ key: "street", label: "Street", placeholder: "12 Baker St" },
{ key: "city", label: "City", placeholder: "London" },
{ key: "zip", label: "Postal code", placeholder: "NW1 6XE" },
{ key: "country", label: "Country", placeholder: "United Kingdom" },
]
return (
<div data-slot="styled-field" className={cn("flex w-full max-w-md flex-col", blockGap[size], className)}>
<span className={cn("font-medium leading-none text-foreground", labelText[size])}>{label}</span>
<div className={cn("grid grid-cols-1 sm:grid-cols-2", blockGap[size])}>
{cells.map((c) => (
<SubField
key={c.key}
id={`${base}-${c.key}`}
size={size}
label={c.label}
placeholder={c.placeholder}
describedBy={descId}
/>
))}
</div>
<GroupDescription id={descId} size={size}>
{description}
</GroupDescription>
</div>
)
}
/* Section: a titled section - a separator line plus the fields under the title. */
export function SectionField({
className,
size = "md",
label = "Account",
description = "These details appear on your invoices.",
}: FieldProps) {
const base = React.useId()
const descId = description != null && description !== false ? `${base}-desc` : undefined
return (
<div
data-slot="styled-field"
className={cn("flex w-full max-w-md flex-col rounded-xl border border-border bg-card p-4 text-card-foreground", blockGap[size], className)}
>
<div className={cn("flex flex-col", gap[size])}>
<h4 className={cn("font-semibold leading-none text-foreground", labelText[size])}>{label}</h4>
<GroupDescription id={descId} size={size}>
{description}
</GroupDescription>
</div>
<div className="h-px w-full bg-border" />
<div className={cn("flex flex-col", blockGap[size])}>
<SubField id={`${base}-company`} size={size} label="Company" placeholder="Acme Inc" describedBy={descId} />
<SubField id={`${base}-vat`} size={size} label="VAT number" placeholder="GB123456789" describedBy={descId} />
</div>
</div>
)
}
/* Fieldset: gercek <fieldset> + <legend>, ilgili kontrolleri semantik olarak grupla. */
export function FieldsetField({
className,
size = "md",
label = "Contact preferences",
description = "Pick how we should reach you.",
}: FieldProps) {
const base = React.useId()
const descId = description != null && description !== false ? `${base}-desc` : undefined
const options = [
{ key: "email", label: "Email" },
{ key: "sms", label: "SMS" },
{ key: "none", label: "Do not contact me" },
]
return (
<fieldset
data-slot="styled-field"
aria-describedby={descId}
className={cn("flex w-full max-w-md flex-col rounded-xl border border-border p-4", blockGap[size], className)}
>
<legend className={cn("px-1 font-medium leading-none text-foreground", labelText[size])}>{label}</legend>
<GroupDescription id={descId} size={size}>
{description}
</GroupDescription>
<div className={cn("flex flex-col", gap[size])}>
{options.map((o) => (
/* min-h-6: because a native <input> is a replaced element, the ::after hit-area recipe does NOT work THERE (the pseudo-element is not rendered). The fix is to seat the row on a 24px base: the input stays 16x16 but neighbouring input centres are >=24px apart, which satisfies WCAG 2.5.8's spacing exception. The label is already bound with htmlFor, so the clickable area covers the text as well. */
<div key={o.key} className="flex min-h-6 items-center gap-2">
<input
type="radio"
id={`${base}-${o.key}`}
name={`${base}-contact`}
defaultChecked={o.key === "email"}
className="size-4 shrink-0 accent-primary outline-none focus-visible:ring-[3px] focus-visible:ring-ring/50"
/>
<label htmlFor={`${base}-${o.key}`} className={cn("leading-none text-foreground select-none", helpText[size])}>
{o.label}
</label>
</div>
))}
</div>
</fieldset>
)
}Manual installs skip the @ai2/tokens theme, so add the token CSS from the theming guide or the tone colors will be missing.
Variations
5 takes on the same idea. Each is its own export, and every one accepts a size prop (sm, md, lg, xl) aligned to the base Button scale.
Row
Two equal fields side by side under one shared heading.
As it appears on your ID.
import { RowField } from "@/components/ui/field-group"
<RowField />As it appears on your ID.
As it appears on your ID.
As it appears on your ID.
As it appears on your ID.
Split
An asymmetric split: a wide primary field and a narrow secondary one.
Enter the amount and pick a currency.
import { SplitField } from "@/components/ui/field-group"
<SplitField />Enter the amount and pick a currency.
Enter the amount and pick a currency.
Enter the amount and pick a currency.
Enter the amount and pick a currency.
Grid
A two column grid of four fields that collapses on narrow screens.
We ship to these details exactly as written.
import { GridField } from "@/components/ui/field-group"
<GridField />We ship to these details exactly as written.
We ship to these details exactly as written.
We ship to these details exactly as written.
We ship to these details exactly as written.
Section
A titled card section with a divider above its fields.
Account
These details appear on your invoices.
import { SectionField } from "@/components/ui/field-group"
<SectionField />Account
These details appear on your invoices.
Account
These details appear on your invoices.
Account
These details appear on your invoices.
Account
These details appear on your invoices.
Fieldset
A real fieldset and legend grouping related radio controls.
import { FieldsetField } from "@/components/ui/field-group"
<FieldsetField />ai2 Group fields: 5 styled variations on the token system
The ai2 Group fields are a set of 5 decorative button variations from the styled layer of the @ai2 design system, built around layouts for several related fields in one block. They are free and MIT licensed, and every color comes from a semantic token, so they theme with the rest of ai2 in light and dark.
Motion runs on framer-motion: these are static layouts; no motion library work is required. The styled layer is opt-in, so the dependency only lands if you use it; the base components stay lean. Under reduced motion, there is no motion to reduce.
What is in the ai2 Group fields?
5 exports in one file: Row, Split, Grid, Section and Fieldset. Each renders a native button and takes a size prop (sm, md, lg, xl) aligned to the base Button. They are separate from the base Button on purpose: the base keeps its clean variant, tone and size axes, while the styled layer carries the effects.
You own the file. Copy the one category file and you have all 5 variations, with no runtime dependency on ai2 itself.
Why use it
- On-system by construction: Every color resolves to an ai2 semantic token, so the buttons follow your theme in light and dark with no extra work.
- Effect without the sprawl: The decorations live in a dedicated styled file, so the base Button keeps its clean, predictable API.
- Accessible and honest: Each renders a real button element, keeps a visible focus ring, and respects prefers-reduced-motion.
Features
- Token-driven color: No hardcoded hex or oklch; the look recolors with your theme tokens.
- framer-motion: these are static layouts; no motion library work is required.
- Reduced-motion aware: Under prefers-reduced-motion, there is no motion to reduce.
- Size aligned to the base: Every variation takes sm, md, lg and xl matching the base Button height scale, so styled and base buttons line up in a row.
Production tips
- Use it for emphasis, not everywhere: Styled buttons draw the eye. Reserve them for the one action you want people to take on a screen, and use the base Button for the rest.
- Keep labels as verbs: The decoration adds weight, so a clear action label keeps the button scannable.
- Pick one variation per surface: The variations share a family; using two different ones in the same view competes for attention.
Works with the rest of ai2
The Group fields sit alongside the base Button and the rest of the @ai2 registry. They share the same token file, so a styled action next to a base button or a badge stays visually consistent in both modes.