Field

Combine labels, controls, and help text to compose accessible form fields and grouped inputs.

Profile

Update your public profile information.

1
import {
2
  Field,
3
  FieldDescription,
4
  FieldGroup,
5
  FieldLabel,
6
  FieldLegend,
7
  FieldSet,
8
} from "@/components/ui/pxl/field";
9
import { Input } from "@/components/ui/pxl/input";
10

11
export default function FieldDemo() {
12
  return (
13
    <FieldSet className="w-full max-w-md">
14
      <FieldLegend>Profile</FieldLegend>
15
      <FieldDescription>
16
        Update your public profile information.
17
      </FieldDescription>
18
      <FieldGroup>
19
        <Field>
20
          <FieldLabel htmlFor="field-name">Name</FieldLabel>
21
          <Input id="field-name" placeholder="Evil Rabbit" />
22
          <FieldDescription>This is your public display name.</FieldDescription>
23
        </Field>
24
        <Field>
25
          <FieldLabel htmlFor="field-email">Email</FieldLabel>
26
          <Input id="field-email" placeholder="you@example.com" type="email" />
27
        </Field>
28
      </FieldGroup>
29
    </FieldSet>
30
  );
31
}

Installation

Command
Manual

pnpm dlx shadcn@latest add pxl-ui/registry/field

Copy and paste the following code into your project.

1
"use client";
2

3
import { cva, type VariantProps } from "class-variance-authority";
4
import { useMemo } from "react";
5

6
import { Label } from "@/components/ui/pxl/label";
7
import { Separator } from "@/components/ui/pxl/separator";
8
import { cn } from "@/lib/utils";
9

10
function FieldSet({ className, ...props }: React.ComponentProps<"fieldset">) {
11
  return (
12
    <fieldset
13
      data-slot="field-set"
14
      className={cn(
15
        "flex flex-col gap-6 has-[>[data-slot=checkbox-group]]:gap-3 has-[>[data-slot=radio-group]]:gap-3",
16
        className,
17
      )}
18
      {...props}
19
    />
20
  );
21
}
22

23
function FieldLegend({
24
  className,
25
  variant = "legend",
26
  ...props
27
}: React.ComponentProps<"legend"> & { variant?: "legend" | "label" }) {
28
  return (
29
    <legend
30
      data-slot="field-legend"
31
      data-variant={variant}
32
      className={cn(
33
        "mb-3 font-heading data-[variant=label]:text-sm data-[variant=legend]:text-base",
34
        className,
35
      )}
36
      {...props}
37
    />
38
  );
39
}
40

41
function FieldGroup({ className, ...props }: React.ComponentProps<"div">) {
42
  return (
43
    <div
44
      data-slot="field-group"
45
      className={cn(
46
        "group/field-group @container/field-group flex w-full flex-col gap-7 data-[slot=checkbox-group]:gap-3 *:data-[slot=field-group]:gap-4",
47
        className,
48
      )}
49
      {...props}
50
    />
51
  );
52
}
53

54
const fieldVariants = cva(
55
  "group/field flex w-full gap-3 data-[invalid=true]:text-destructive",
56
  {
57
    variants: {
58
      orientation: {
59
        vertical: "flex-col *:w-full [&>.sr-only]:w-auto",
60
        horizontal:
61
          "flex-row items-center has-[>[data-slot=field-content]]:items-start *:data-[slot=field-label]:flex-auto has-[>[data-slot=field-content]]:[&>[role=checkbox],[role=radio]]:mt-px",
62
        responsive:
63
          "flex-col *:w-full @md/field-group:flex-row @md/field-group:items-center @md/field-group:*:w-auto @md/field-group:has-[>[data-slot=field-content]]:items-start @md/field-group:*:data-[slot=field-label]:flex-auto [&>.sr-only]:w-auto @md/field-group:has-[>[data-slot=field-content]]:[&>[role=checkbox],[role=radio]]:mt-px",
64
      },
65
    },
66
    defaultVariants: {
67
      orientation: "vertical",
68
    },
69
  },
70
);
71

72
function Field({
73
  className,
74
  orientation = "vertical",
75
  ...props
76
}: React.ComponentProps<"div"> & VariantProps<typeof fieldVariants>) {
77
  return (
78
    // biome-ignore lint/a11y/useSemanticElements: field
79
    <div
80
      role="group"
81
      data-slot="field"
82
      data-orientation={orientation}
83
      className={cn(fieldVariants({ orientation }), className)}
84
      {...props}
85
    />
86
  );
87
}
88

89
function FieldContent({ className, ...props }: React.ComponentProps<"div">) {
90
  return (
91
    <div
92
      data-slot="field-content"
93
      className={cn(
94
        "group/field-content flex flex-1 flex-col gap-1 leading-snug",
95
        className,
96
      )}
97
      {...props}
98
    />
99
  );
100
}
101

102
function FieldLabel({
103
  className,
104
  ...props
105
}: React.ComponentProps<typeof Label>) {
106
  return (
107
    <Label
108
      data-slot="field-label"
109
      className={cn(
110
        "group/field-label peer/field-label flex w-fit gap-2 leading-snug font-heading group-data-[disabled=true]/field:opacity-50 has-data-checked:border-primary/30 has-data-checked:bg-primary/5 has-[>[data-slot=field]]:pixel-rounded has-[>[data-slot=field]]:pixel-border has-[>[data-slot=field]]:pixel-size-[3px] *:data-[slot=field]:p-3 dark:has-data-checked:border-primary/20 dark:has-data-checked:bg-primary/10",
111
        "has-[>[data-slot=field]]:w-full has-[>[data-slot=field]]:flex-col",
112
        className,
113
      )}
114
      {...props}
115
    />
116
  );
117
}
118

119
function FieldTitle({ className, ...props }: React.ComponentProps<"div">) {
120
  return (
121
    <div
122
      data-slot="field-label"
123
      className={cn(
124
        "flex w-fit items-center gap-2 text-sm group-data-[disabled=true]/field:opacity-50",
125
        className,
126
      )}
127
      {...props}
128
    />
129
  );
130
}
131

132
function FieldDescription({ className, ...props }: React.ComponentProps<"p">) {
133
  return (
134
    <p
135
      data-slot="field-description"
136
      className={cn(
137
        "text-left text-sm leading-normal font-normal text-muted-foreground group-has-data-horizontal/field:text-balance [[data-variant=legend]+&]:-mt-1.5",
138
        "last:mt-0 nth-last-2:-mt-1",
139
        "[&>a]:underline [&>a]:underline-offset-4 [&>a:hover]:text-primary",
140
        className,
141
      )}
142
      {...props}
143
    />
144
  );
145
}
146

147
function FieldSeparator({
148
  children,
149
  className,
150
  ...props
151
}: React.ComponentProps<"div"> & {
152
  children?: React.ReactNode;
153
}) {
154
  return (
155
    <div
156
      data-slot="field-separator"
157
      data-content={!!children}
158
      className={cn(
159
        "relative -my-2 h-5 text-sm group-data-[variant=outline]/field-group:-mb-2",
160
        className,
161
      )}
162
      {...props}
163
    >
164
      <Separator className="absolute inset-0 top-1/2" />
165
      {children && (
166
        <span
167
          className="relative mx-auto block w-fit bg-background px-2 text-muted-foreground"
168
          data-slot="field-separator-content"
169
        >
170
          {children}
171
        </span>
172
      )}
173
    </div>
174
  );
175
}
176

177
function FieldError({
178
  className,
179
  children,
180
  errors,
181
  ...props
182
}: React.ComponentProps<"div"> & {
183
  errors?: Array<{ message?: string } | undefined>;
184
}) {
185
  const content = useMemo(() => {
186
    if (children) {
187
      return children;
188
    }
189

190
    if (!errors?.length) {
191
      return null;
192
    }
193

194
    const uniqueErrors = [
195
      ...new Map(errors.map((error) => [error?.message, error])).values(),
196
    ];
197

198
    if (uniqueErrors?.length === 1) {
199
      return uniqueErrors[0]?.message;
200
    }
201

202
    return (
203
      <ul className="ml-4 flex list-disc flex-col gap-1">
204
        {uniqueErrors.map(
205
          (error, index) =>
206
            error?.message && <li key={index.toString()}>{error.message}</li>,
207
        )}
208
      </ul>
209
    );
210
  }, [children, errors]);
211

212
  if (!content) {
213
    return null;
214
  }
215

216
  return (
217
    <div
218
      role="alert"
219
      data-slot="field-error"
220
      className={cn("text-sm font-normal text-destructive", className)}
221
      {...props}
222
    >
223
      {content}
224
    </div>
225
  );
226
}
227

228
export {
229
  Field,
230
  FieldContent,
231
  FieldDescription,
232
  FieldError,
233
  FieldGroup,
234
  FieldLabel,
235
  FieldLegend,
236
  FieldSeparator,
237
  FieldSet,
238
  FieldTitle,
239
};

Update the import paths to match your project setup.

Usage

import {
  Field,
  FieldContent,
  FieldDescription,
  FieldError,
  FieldGroup,
  FieldLabel,
  FieldLegend,
  FieldSeparator,
  FieldSet,
  FieldTitle,
} from "@/components/ui/pxl/field"

<FieldSet>
  <FieldLegend>Profile</FieldLegend>
  <FieldDescription>This appears on invoices and emails.</FieldDescription>
  <FieldGroup>
    <Field>
      <FieldLabel htmlFor="name">Full name</FieldLabel>
      <Input id="name" autoComplete="off" placeholder="Evil Rabbit" />
      <FieldDescription>This appears on invoices and emails.</FieldDescription>
    </Field>
    <Field>
      <FieldLabel htmlFor="username">Username</FieldLabel>
      <Input id="username" autoComplete="off" aria-invalid />
      <FieldError>Choose another username.</FieldError>
    </Field>
    <Field orientation="horizontal">
      <Switch id="newsletter" />
      <FieldLabel htmlFor="newsletter">Subscribe to the newsletter</FieldLabel>
    </Field>
  </FieldGroup>
</FieldSet>

Composition

Field

A single control with label, helper text, and validation.

Field
├── FieldLabel
├── Input / Textarea / Switch / Select
├── FieldDescription
└── FieldError

FieldGroup

Related fields in one group. Use FieldSeparator between sections when needed.

FieldGroup
├── Field
│   ├── FieldLabel
│   ├── Input / Textarea / Switch / Select
│   ├── FieldDescription
│   └── FieldError
├── FieldSeparator
└── Field
    ├── FieldLabel
    └── Input / Textarea / Switch / Select

FieldSet

Semantic grouping with a legend and description, usually containing a FieldGroup.

FieldSet
├── FieldLegend
├── FieldDescription
└── FieldGroup
    ├── Field
    │   ├── FieldLabel
    │   ├── Input / Textarea / Switch / Select
    │   ├── FieldDescription
    │   └── FieldError
    └── Field
        ├── FieldLabel
        └── Input / Textarea / Switch / Select

Anatomy

The Field family is designed for composing accessible forms. A typical field is structured as follows:

1
<Field>
2
  <FieldLabel htmlFor="input-id">Label</FieldLabel>
3
  {/* Input, Select, Switch, etc. */}
4
  <FieldDescription>Optional helper text.</FieldDescription>
5
  <FieldError>Validation message.</FieldError>
6
</Field>

Field is the core wrapper for a single field.
FieldContent is a flex column that groups label and description. Not required if you have no description.
Wrap related fields with FieldGroup, and use FieldSet with FieldLegend for semantic grouping.

Form

See the Form documentation for building forms with the Field component and React Hook Form, Tanstack Form, or Formisch.

Responsive Layout

Vertical fields: Default orientation stacks label, control, and helper text—ideal for mobile-first layouts.
Horizontal fields: Set orientation="horizontal" on Field to align the label and control side-by-side. Pair with FieldContent to keep descriptions aligned.
Responsive fields: Set orientation="responsive" for automatic column layouts inside container-aware parents. Apply @container/field-group classes on FieldGroup to switch orientations at specific breakpoints.

Validation and Errors

Add data-invalid to Field to switch the entire block into an error state.
Add aria-invalid on the input itself for assistive technologies.
Render FieldError immediately after the control or inside FieldContent to keep error messages aligned with the field.

1
<Field data-invalid>
2
  <FieldLabel htmlFor="email">Email</FieldLabel>
3
  <Input id="email" type="email" aria-invalid />
4
  <FieldError>Enter a valid email address.</FieldError>
5
</Field>

Accessibility

FieldSet and FieldLegend keep related controls grouped for keyboard and assistive tech users.
Field outputs role="group" so nested controls inherit labeling from FieldLabel and FieldLegend when combined.
Apply FieldSeparator sparingly to ensure screen readers encounter clear section boundaries.

API Reference

FieldSet

Container that renders a semantic fieldset with spacing presets.

Prop	Type	Default
`className`	`string`

<FieldSet>
  <FieldLegend>Delivery</FieldLegend>
  <FieldGroup>{/* Fields */}</FieldGroup>
</FieldSet>

FieldLegend

Legend element for a FieldSet. Switch to the label variant to align with label sizing.

Prop	Type	Default
`variant`	`"legend" \| "label"`	`"legend"`
`className`	`string`

<FieldLegend variant="label">Notification Preferences</FieldLegend>

The FieldLegend has two variants: legend and label. The label variant applies label sizing and alignment. Handy if you have nested FieldSet.

FieldGroup

Layout wrapper that stacks Field components and enables container queries for responsive orientations.

Prop	Type	Default
`className`	`string`

<FieldGroup className="@container/field-group flex flex-col gap-6">
  <Field>{/* ... */}</Field>
  <Field>{/* ... */}</Field>
</FieldGroup>

Field

The core wrapper for a single field. Provides orientation control, invalid state styling, and spacing.

Prop	Type	Default
`orientation`	`"vertical" \| "horizontal" \| "responsive"`	`"vertical"`
`className`	`string`
`data-invalid`	`boolean`

<Field orientation="horizontal">
  <FieldLabel htmlFor="remember">Remember me</FieldLabel>
  <Switch id="remember" />
</Field>

FieldContent

Flex column that groups control and descriptions when the label sits beside the control. Not required if you have no description.

Prop	Type	Default
`className`	`string`

<Field>
  <Checkbox id="notifications" />
  <FieldContent>
    <FieldLabel htmlFor="notifications">Notifications</FieldLabel>
    <FieldDescription>Email, SMS, and push options.</FieldDescription>
  </FieldContent>
</Field>

FieldLabel

Label styled for both direct inputs and nested Field children.

Prop	Type	Default
`className`	`string`

<FieldLabel htmlFor="email">Email</FieldLabel>

FieldTitle

Renders a title with label styling inside FieldContent.

Prop	Type	Default
`className`	`string`

<FieldContent>
  <FieldTitle>Enable Touch ID</FieldTitle>
  <FieldDescription>Unlock your device faster.</FieldDescription>
</FieldContent>

FieldDescription

Helper text slot that automatically balances long lines in horizontal layouts.

Prop	Type	Default
`className`	`string`

<FieldDescription>We never share your email with anyone.</FieldDescription>

FieldSeparator

Visual divider to separate sections inside a FieldGroup. Accepts optional inline content.

Prop	Type	Default
`className`	`string`

<FieldSeparator>Or continue with</FieldSeparator>

FieldError

Accessible error container that accepts children or an errors array (e.g., from react-hook-form).

Prop	Type	Default
`errors`	`Array<{ message?: string } \| undefined>`
`className`	`string`

<FieldError errors={errors.username} />

When the errors array contains multiple messages, the component renders a list automatically.

FieldError also accepts issues produced by any validator that implements Standard Schema, including Zod, Valibot, and ArkType. Pass the issues array from the schema result directly to render a unified error list across libraries.