FormField

A composable form field wrapper that combines label, control, description, and error message into a consistent accessible layout.

Overview

The FormField component composes a label, form control slot, optional description/helper text, and error message into a single consistent layout. It automatically generates and wires up htmlFor, aria-describedby, and aria-invalid attributes for full accessibility.

Installation

Install the component via the CLI in one command.

npx @work-rjkashyap/unified-ui add form-field

pnpm dlx @work-rjkashyap/unified-ui add form-field

npx @work-rjkashyap/unified-ui add form-field

bunx @work-rjkashyap/unified-ui add form-field

If you haven't initialized your project yet, run npx @work-rjkashyap/unified-ui init first. See the CLI docs for details.

Or install the full package

Use this approach if you prefer to install the entire design system as a dependency instead of copying individual components.

npm install @work-rjkashyap/unified-ui

pnpm add @work-rjkashyap/unified-ui

yarn add @work-rjkashyap/unified-ui

bun add @work-rjkashyap/unified-ui

Anatomy

import { FormField } from "@work-rjkashyap/unified-ui";

Examples

Basic Usage

Full name

<FormField label="Full name">
<Input placeholder="Enter your name" />
</FormField>

<FormField label="Email">
<Input type="email" placeholder="you@example.com" />
</FormField>

<FormField label="Full name"><Input placeholder="Enter your name" /></FormField><FormField label="Email"><Input type="email" placeholder="you@example.com" /></FormField>

Required Fields

Username

Password

<FormField label="Username" required>
<Input placeholder="Choose a username" />
</FormField>

<FormField label="Password" required>
<Input type="password" placeholder="••••••••" />
</FormField>

<FormField label="Username" required><Input placeholder="Choose a username" /></FormField><FormField label="Password" required><Input type="password" placeholder="••••••••" /></FormField>

Error State

Please enter a valid email address.

Password

Password must be at least 8 characters.

<FormField label="Email" required error="Please enter a valid email address.">
<Input variant="error" placeholder="you@example.com" />
</FormField>

<FormField label="Password" required error="Password must be at least 8 characters.">
<Input variant="error" type="password" placeholder="••••••••" />
</FormField>

<FormField label="Email" required error="Please enter a valid email address."><Input variant="error" placeholder="you@example.com" /></FormField><FormField label="Password" required error="Password must be at least 8 characters."><Input variant="error" type="password" placeholder="••••••••" /></FormField>

Sizes

Small field

Medium field

Large field

<FormField label="Small field" size="sm">
<Input size="sm" placeholder="Small input" />
</FormField>

<FormField
label="Medium field"
size="md"
>
<Input size="md" placeholder="Medium input" />
</FormField>

<FormField label="Large field" size="lg">
<Input size="lg" placeholder="Large input" />
</FormField>

<FormField label="Small field" size="sm"><Input size="sm" placeholder="Small input" /></FormField><FormFieldlabel="Medium field"size="md"><Input size="md" placeholder="Medium input" /></FormField><FormField label="Large field" size="lg"><Input size="lg" placeholder="Large input" /></FormField>

Horizontal Layout

Display name

Bio

Website

Please enter a valid URL.

<FormField label="Display name" orientation="horizontal">
<Input placeholder="Your display name" />
</FormField>

<FormField
label="Bio"
orientation="horizontal"
>
<Textarea placeholder="Tell us about yourself" />
</FormField>

<FormField label="Website" orientation="horizontal" error="Please enter a valid URL.">
<Input variant="error" placeholder="https://example.com" />
</FormField>

<FormField label="Display name" orientation="horizontal"><Input placeholder="Your display name" /></FormField><FormFieldlabel="Bio"orientation="horizontal"><Textarea placeholder="Tell us about yourself" /></FormField><FormField label="Website" orientation="horizontal" error="Please enter a valid URL."><Input variant="error" placeholder="https://example.com" /></FormField>

Disabled State

Organization

Render Function (Auto-wired Accessibility)

For maximum accessibility, use the render function form of children to receive and spread control props automatically:

<FormField label="Email" required error={errors.email}>
	{(controlProps) => (
		<Input {...controlProps} type="email" placeholder="you@example.com" />
	)}
</FormField>

The render function receives:

Prop	Type	Description
`id`	`string`	Auto-generated id to set on the control.
`aria-describedby`	`string`	ID(s) of description and/or error elements.
`aria-invalid`	`boolean`	`true` when an error is present.
`aria-required`	`boolean`	`true` when the field is required.
`disabled`	`boolean`	`true` when the field is disabled.

Props

Prop	Type	Default	Description
`label`	`ReactNode`	—	Label text for the form field.
`description`	`ReactNode`	—	Helper text below the label or control.
`error`	`ReactNode`	—	Error message (replaces description when present).
`size`	`"sm" \| "md" \| "lg"`	`"md"`	Controls label size, spacing, and context.
`orientation`	`"vertical" \| "horizontal"`	`"vertical"`	Layout orientation for label + control.
`required`	`boolean`	`false`	Shows a red asterisk and sets `aria-required` via render fn.
`disabled`	`boolean`	`false`	Reduces opacity on all visual elements.
`htmlFor`	`string`	auto	ID for the form control. Auto-generated if omitted.
`children`	`ReactNode \| (props: ControlProps) => ReactNode`	—	The form control(s) or render function.
`labelClassName`	`string`	—	Additional CSS classes for the label.
`descriptionClassName`	`string`	—	Additional CSS classes for the description.
`errorClassName`	`string`	—	Additional CSS classes for the error message.
`controlClassName`	`string`	—	Additional CSS classes for the control wrapper.
`className`	`string`	—	Additional CSS classes for the root element.

Accessibility

Use the render function form of children for automatic id, aria-describedby, aria-invalid, and aria-required wiring on the control.

Label linkage — The label's htmlFor is automatically linked to the control's id.
Description — Linked to the control via aria-describedby.
Error message — Replaces description in aria-describedby and renders with role="alert".
Required — Visual indicator plus aria-required (via render function).
Disabled — Visual reduction on all elements; disable the control separately.

Design Tokens

Token	Usage
`--foreground`	Label text color
`--danger`	Required indicator & error text
`--muted-foreground`	Description text color

On this page