# Field

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

```tsx
import * as stylex from "@stylexjs/stylex"
import { Button } from "@/components/ui/button"
import { Checkbox } from "@/components/ui/checkbox"
import { Field, FieldDescription, FieldGroup, FieldLabel, FieldSeparator } from "@/components/ui/field"
import { FieldsetLegend, Fieldset } from "@/components/ui/fieldset"
import { Input } from "@/components/ui/input"
import { space } from "@/theme/tokens.stylex"
import { widths } from "@/theme/widths"

const styles = stylex.create({
  columns: { display: "grid", gridTemplateColumns: "repeat(3, minmax(0, 1fr))", gap: space.s4 },
})

export default function FieldDemo() {
  return (
    <form {...stylex.props(widths.md)} onSubmit={(event) => event.preventDefault()}>
      <FieldGroup>
        <Fieldset>
          <FieldsetLegend>Card Details</FieldsetLegend>
          <FieldDescription>We charge this card on the first of each month</FieldDescription>
          <FieldGroup>
            <Field>
              <FieldLabel>Cardholder Name</FieldLabel>
              <Input id="checkout-card-name" placeholder="Ada Lovelace" required />
            </Field>
            <Field>
              <FieldLabel>Card Number</FieldLabel>
              <Input id="checkout-card-number" placeholder="0000 0000 0000 0000" required />
              <FieldDescription>The 16 digits on the front of the card</FieldDescription>
            </Field>
            <div {...stylex.props(styles.columns)}>
              <Field>
                <FieldLabel>Month</FieldLabel>
                <Input id="checkout-exp-month" placeholder="MM" required />
              </Field>
              <Field>
                <FieldLabel>Year</FieldLabel>
                <Input id="checkout-exp-year" placeholder="YYYY" required />
              </Field>
              <Field>
                <FieldLabel>CVV</FieldLabel>
                <Input id="checkout-cvv" placeholder="123" required />
              </Field>
            </div>
          </FieldGroup>
        </Fieldset>
        <FieldSeparator />
        <Fieldset>
          <FieldsetLegend>Invoice Address</FieldsetLegend>
          <FieldDescription>Where we send the monthly invoice for your lab</FieldDescription>
          <FieldGroup>
            <Field orientation="horizontal">
              <Checkbox id="checkout-use-lab-address" defaultChecked />
              <FieldLabel>Use the lab&apos;s address</FieldLabel>
            </Field>
          </FieldGroup>
        </Fieldset>
        <Field orientation="horizontal">
          <Button type="submit">Submit</Button>
          <Button variant="outline" type="button">
            Cancel
          </Button>
        </Field>
      </FieldGroup>
    </form>
  )
}
```

## Installation

**Command**

```bash
npx shadcn@latest add @arene/field
```

Needs the [arene setup](https://www.arene.style/docs/installation) first. Also adds [Label](https://www.arene.style/docs/components/label), [Separator](https://www.arene.style/docs/components/separator) and [Stack](https://www.arene.style/docs/components/stack).

**Manual**

1. Install the packages it imports:

   ```bash
   npm install @base-ui/react @stylexjs/stylex clsx
   ```

2. Set up the token layer and the StyleX compiler, if you have not already. See
   [Installation](https://www.arene.style/docs/installation), and paste `states.ts` from the same page,
   which is where a choice card's focus ring comes from. The field builds on
   [Label](https://www.arene.style/docs/components/label), [Separator](https://www.arene.style/docs/components/separator) and
   [Stack](https://www.arene.style/docs/components/stack), so paste those first. It also needs `interop.css`, which styles a link inside a
   description.

   Paste `field-state.ts` and `state-styles.ts` from the same installation page.
   The choice card's ring also needs the `lib/focus-visible.ts` helper, which
   tells it whether its focus came from the keyboard.

3. Paste the focus-visible helper and the component into your project.

   ```ts title="lib/focus-visible.ts"
   "use client"

   import { useState, type FocusEvent } from "react"

   type FocusHandlers<Event> = {
     onFocus?: (event: Event) => void
     onBlur?: (event: Event) => void
   }

   export function useFocusVisible<Event extends FocusEvent<Element>>({
     onFocus,
     onBlur,
   }: FocusHandlers<Event> = {}) {
     const [focusVisible, setFocusVisible] = useState(false)
     const focusProps = {
       onFocus: (event: Event) => {
         onFocus?.(event)
         setFocusVisible(event.target.matches(":focus-visible"))
       },
       onBlur: (event: Event) => {
         onBlur?.(event)
         setFocusVisible(false)
       },
     }
     return { focusVisible, setFocusVisible, focusProps }
   }
   ```

   ```tsx title="components/ui/field.tsx"
   "use client"

   import type { CSSProperties, ReactNode } from "react"
   import { Children, createContext, isValidElement, use } from "react"
   import { useRender } from "@base-ui/react/use-render"
   import { Field as FieldPrimitive } from "@base-ui/react/field"
   import * as stylex from "@stylexjs/stylex"
   import type { StyleXStyles } from "@stylexjs/stylex"
   import { clsx } from "clsx"

   import { FieldStateContext } from "@/lib/field-state"
   import { useFocusVisible } from "@/lib/focus-visible"
   import { stateStyles } from "@/lib/state-styles"
   import { labelStyles } from "@/components/ui/label"
   import { Separator } from "@/components/ui/separator"
   import { VStack, type SpacingStep } from "@/components/ui/stack"
   import { states } from "@/theme/states"
   import {
     color,
     duration,
     ease,
     leading,
     radius,
     shadow,
     space,
     text,
   } from "@/theme/tokens.stylex"

   type FieldOrientation = keyof typeof orientations

   type FieldState = {
     orientation: FieldOrientation
     inContent: boolean
   }

   const FieldContext = createContext<FieldState | null>(null)

   const GROUP_MD = "@container field-group (width >= 28rem)"

   const styles = stylex.create({
     group: {
       width: "100%",
       containerType: "inline-size",
       containerName: "field-group",
     },
     field: {
       display: "flex",
       width: "100%",
       gap: space.s2,
     },
     horizontalWithContent: { alignItems: "flex-start" },
     responsiveWithContent: { alignItems: { default: "stretch", [GROUP_MD]: "flex-start" } },
     invalid: { color: color.destructive },
     control: { width: { default: "100%", [GROUP_MD]: "auto" } },
     content: {
       display: "flex",
       flexDirection: "column",
       gap: space.s1,
       flexGrow: 1,
       flexShrink: 1,
       flexBasis: "0%",
     },
     label: { width: "fit-content" },
     labelGrow: { flexGrow: 1, flexShrink: 1, flexBasis: "auto" },
     card: {
       width: "100%",
       flexDirection: "column",
       padding: space.s2_5,
       borderRadius: radius.lg,
       borderWidth: 1,
       borderStyle: "solid",
       "--arene-border-color": color.transparent,
       borderColor: "var(--arene-border-color)",
       backgroundColor: color.card,
       "--arene-field-card-surface": shadow.raised,
       boxShadow: "var(--arene-field-card-surface)",
       transitionProperty: "color, background-color, border-color, box-shadow",
       transitionDuration: duration.color,
       transitionTimingFunction: ease.standard,
     },
     cardChecked: { "--arene-border-color": color.foreground },
     cardFocused: { boxShadow: `var(--arene-field-card-surface), ${shadow.ring}` },
     title: {
       display: "flex",
       alignItems: "center",
       gap: space.s2,
       width: "fit-content",
       fontSize: text.sm,
       lineHeight: 1,
       fontWeight: 500,
       "--arene-icon-size": space.s4,
     },
     dimmed: { opacity: 0.5 },
     description: {
       color: color.mutedForeground,
       fontSize: text.sm,
       lineHeight: leading.sm,
       fontWeight: 400,
     },
     descriptionBalanced: { textWrap: "balance" },
     separator: {
       position: "relative",
       height: space.s5,
       marginBlock: `calc(-1 * ${space.s2})`,
       fontSize: text.sm,
       lineHeight: leading.sm,
     },
     separatorLine: {
       position: "absolute",
       insetInline: 0,
       top: "50%",
     },
     separatorContent: {
       position: "relative",
       display: "block",
       width: "fit-content",
       marginInline: "auto",
       paddingInline: space.s2,
       backgroundColor: color.background,
       color: color.mutedForeground,
     },
     error: {
       color: color.destructive,
       fontSize: text.sm,
       lineHeight: leading.sm,
       fontWeight: 400,
     },
     errorList: {
       display: "flex",
       flexDirection: "column",
       gap: space.s1,
       marginInlineStart: space.s4,
       listStyleType: "disc",
     },
   })

   const orientations = stylex.create({
     vertical: { flexDirection: "column" },
     horizontal: { flexDirection: "row", alignItems: "center" },
     responsive: {
       flexDirection: { default: "column", [GROUP_MD]: "row" },
       alignItems: { default: "stretch", [GROUP_MD]: "center" },
     },
   })

   const fieldStyles = {
     field: styles.field,
     orientations,
     invalid: styles.invalid,
     control: styles.control,
     card: styles.card,
     cardChecked: styles.cardChecked,
     cardFocused: [states.ring, styles.cardFocused],
     description: styles.description,
     error: styles.error,
   }

   type StyleProps = {
     xstyle?: StyleXStyles
     className?: string
   }

   type FieldGroupProps = useRender.ComponentProps<"div"> &
     StyleProps & {
       gap?: SpacingStep
     }

   function FieldGroup({ gap = 5, xstyle, className, ...props }: FieldGroupProps) {
     return (
       <VStack
         data-slot="field-group"
         gap={gap}
         xstyle={[styles.group, xstyle]}
         className={className}
         {...props}
       />
     )
   }

   type FieldProps = Omit<FieldPrimitive.Root.Props, "className" | "style"> &
     StyleProps & { style?: CSSProperties; orientation?: FieldOrientation }

   function Field({
     render,
     orientation = "vertical",
     xstyle,
     className,
     style,
     children,
     ...props
   }: FieldProps) {
     const hasContent = Children.toArray(children).some(
       (child) => isValidElement(child) && child.type === FieldContent,
     )
     return (
       <FieldContext value={{ orientation, inContent: false }}>
         <FieldPrimitive.Root
           data-slot="field"
           data-orientation={orientation}
           {...props}
           {...stateStyles(
             (state) => [
               styles.field,
               orientations[orientation],
               hasContent && orientation === "horizontal" && styles.horizontalWithContent,
               hasContent && orientation === "responsive" && styles.responsiveWithContent,
               (state.valid === false || props.invalid) && styles.invalid,
               xstyle,
             ],
             { className, style },
           )}
           render={(rootProps, state) => (
             <FieldStateContext value={{ ...state, valid: props.invalid ? false : state.valid }}>
               <FieldHost {...rootProps} render={render} fieldState={state} />
             </FieldStateContext>
           )}
         >
           {children}
         </FieldPrimitive.Root>
       </FieldContext>
     )
   }

   function FieldHost({
     render,
     ref,
     fieldState,
     ...props
   }: useRender.ComponentProps<"div", FieldPrimitive.Root.State> & {
     fieldState: FieldPrimitive.Root.State
   }) {
     return useRender({ defaultTagName: "div", render, ref, state: { ...fieldState }, props })
   }

   function FieldContent({
     render,
     ref,
     style,
     xstyle,
     className,
     children,
     ...props
   }: useRender.ComponentProps<"div"> & StyleProps) {
     const field = use(FieldContext)
     const sx = stylex.props(styles.content, xstyle)

     return (
       <FieldContext value={field && { ...field, inContent: true }}>
         {useRender({
           defaultTagName: "div",
           render,
           ref,
           props: {
             "data-slot": "field-content",
             ...sx,
             ...props,
             className: clsx(sx.className, className),
             style: { ...sx.style, ...style },
             children,
           },
         })}
       </FieldContext>
     )
   }

   type FieldLabelProps = Omit<FieldPrimitive.Label.Props, "className" | "style"> &
     StyleProps & {
       style?: CSSProperties
       disabled?: boolean
       checked?: boolean
     }

   function FieldItem({
     xstyle,
     className,
     style,
     ...props
   }: Omit<FieldPrimitive.Item.Props, "className" | "style"> &
     StyleProps & { style?: CSSProperties }) {
     return (
       <FieldPrimitive.Item
         data-slot="field-item"
         {...props}
         {...stateStyles(() => [xstyle], { className, style })}
       />
     )
   }

   function FieldLabel({
     style,
     checked,
     disabled,
     xstyle,
     className,
     children,
     onFocus,
     onBlur,
     ...props
   }: FieldLabelProps) {
     const field = use(FieldContext)
     const card = Children.toArray(children).some(
       (child) => isValidElement(child) && child.type === Field,
     )
     const { focusVisible, focusProps } = useFocusVisible({ onFocus, onBlur })
     const focused = card && focusVisible
     const grows = field !== null && !field.inContent && field.orientation !== "vertical"
     const resolve = (isDisabled: boolean) => [
       labelStyles.base,
       isDisabled && labelStyles.disabled,
       styles.label,
       grows && styles.labelGrow,
       card && fieldStyles.card,
       card && checked && fieldStyles.cardChecked,
       focused && fieldStyles.cardFocused,
       xstyle,
     ]
     const sx = stylex.props(...resolve(!!disabled))
     const { render, ref, nativeLabel, ...hostProps } = props
     const host = useRender({
       defaultTagName: "label",
       render,
       ref,
       enabled: !field,
       state: {
         disabled: !!disabled,
         valid: null,
         dirty: false,
         touched: false,
         filled: false,
         focused,
       },
       props: {
         ...hostProps,
         ...focusProps,
         "data-slot": "field-label",
         "data-checked": card && checked ? "" : undefined,
         className: clsx("arene-icons", sx.className, className),
         style: { ...sx.style, ...style },
         children,
       },
     })
     if (!field) return host
     return (
       <FieldPrimitive.Label
         data-slot="field-label"
         data-checked={card && checked ? "" : undefined}
         {...props}
         nativeLabel={nativeLabel}
         {...focusProps}
         {...stateStyles((state) => resolve(disabled ?? state.disabled), {
           className,
           style,
           hook: "arene-icons",
         })}
       >
         {children}
       </FieldPrimitive.Label>
     )
   }

   function FieldTitle({
     render,
     ref,
     style,
     xstyle,
     className,
     ...props
   }: useRender.ComponentProps<"div"> & StyleProps) {
     const state = use(FieldStateContext)
     const sx = stylex.props(styles.title, state?.disabled && styles.dimmed, xstyle)

     return useRender({
       defaultTagName: "div",
       render,
       ref,
       props: {
         "data-slot": "field-title",
         ...sx,
         ...props,
         className: clsx("arene-icons", sx.className, className),
         style: { ...sx.style, ...style },
       },
     })
   }

   function FieldDescription({
     xstyle,
     className,
     style,
     ...props
   }: Omit<FieldPrimitive.Description.Props, "className" | "style"> &
     StyleProps & { style?: CSSProperties }) {
     const field = use(FieldContext)
     const { render, ref, ...hostProps } = props
     const sx = stylex.props(styles.description, xstyle)
     const host = useRender({
       defaultTagName: "p",
       render,
       ref,
       enabled: !field,
       state: {
         disabled: false,
         valid: null,
         dirty: false,
         touched: false,
         filled: false,
         focused: false,
       },
       props: {
         ...hostProps,
         "data-slot": "field-description",
         className: clsx(sx.className, className),
         style: { ...sx.style, ...style },
       },
     })
     if (!field) return host
     return (
       <FieldPrimitive.Description
         data-slot="field-description"
         {...props}
         {...stateStyles(
           () => [
             styles.description,
             field.orientation !== "vertical" && styles.descriptionBalanced,
             xstyle,
           ],
           { className, style },
         )}
       />
     )
   }

   function FieldSeparator({
     render,
     ref,
     style,
     children,
     xstyle,
     className,
     ...props
   }: useRender.ComponentProps<"div"> & StyleProps) {
     const sx = stylex.props(styles.separator, xstyle)

     return useRender({
       defaultTagName: "div",
       render,
       ref,
       state: { content: !!children },
       props: {
         "data-slot": "field-separator",
         ...sx,
         ...props,
         className: clsx(sx.className, className),
         style: { ...sx.style, ...style },
         children: (
           <>
             <Separator data-slot="field-separator-line" xstyle={styles.separatorLine} />
             {children && (
               <span data-slot="field-separator-content" {...stylex.props(styles.separatorContent)}>
                 {children}
               </span>
             )}
           </>
         ),
       },
     })
   }

   type FieldErrorProps = Omit<FieldPrimitive.Error.Props, "className" | "style"> &
     StyleProps & { style?: CSSProperties; errors?: Array<{ message?: string } | undefined> }
   function FieldError({ errors, children, xstyle, className, style, ...props }: FieldErrorProps) {
     const field = use(FieldContext)
     const fieldState = use(FieldStateContext)
     const content = children ?? errorContent(errors)
     const { render, ref, match, ...hostProps } = props
     const sx = stylex.props(styles.error, xstyle)
     const host = useRender({
       defaultTagName: "div",
       render,
       ref,
       enabled: !field && !!content,
       state: {
         disabled: false,
         valid: false,
         dirty: false,
         touched: false,
         filled: false,
         focused: false,
         transitionStatus: undefined,
       },
       props: {
         ...hostProps,
         role: "alert",
         "data-slot": "field-error",
         className: clsx(sx.className, className),
         style: { ...sx.style, ...style },
         children: content,
       },
     })
     if (!field) return host
     return (
       <FieldPrimitive.Error
         data-slot="field-error"
         role="alert"
         {...props}
         match={
           match ??
           (errors !== undefined
             ? !!content
             : content != null && fieldState?.valid === false && !fieldState.disabled
               ? true
               : undefined)
         }
         {...stateStyles(() => [styles.error, xstyle], { className, style })}
         {...(content != null ? { children: content } : {})}
       />
     )
   }

   const FieldValidity = FieldPrimitive.Validity

   function errorContent(errors: FieldErrorProps["errors"]): ReactNode {
     if (!errors?.length) return null

     const messages = [...new Set(errors.map((error) => error?.message).filter(Boolean))]
     if (messages.length === 0) return null
     if (messages.length === 1) return messages[0]

     return (
       <ul {...stylex.props(styles.errorList)}>
         {messages.map((message) => (
           <li key={message}>{message}</li>
         ))}
       </ul>
     )
   }

   export {
     Field,
     FieldContent,
     FieldItem,
     FieldDescription,
     FieldError,
     FieldGroup,
     FieldLabel,
     FieldSeparator,
     FieldTitle,
     FieldValidity,
     fieldStyles,
     type FieldOrientation,
   }
   ```

4. Change the `@/` imports if your project uses different aliases.

Use [Fieldset](https://www.arene.style/docs/components/fieldset) to group related fields.

## Usage

```tsx
import {
  Field,
  FieldContent,
  FieldDescription,
  FieldError,
  FieldGroup,
  FieldLabel,
  FieldSeparator,
  FieldTitle,
} from "@/components/ui/field"
import { FieldsetLegend, Fieldset } from "@/components/ui/fieldset"
```

```tsx
<Fieldset>
  <FieldsetLegend>Profile</FieldsetLegend>
  <FieldDescription>Shown on every notebook entry you write.</FieldDescription>
  <FieldGroup>
    <Field>
      <FieldLabel>Full name</FieldLabel>
      <Input id="name" autoComplete="off" placeholder="Ada Lovelace" />
      <FieldDescription>Use the name you publish under.</FieldDescription>
    </Field>
    <Field invalid>
      <FieldLabel>Username</FieldLabel>
      <Input id="username" autoComplete="off" />
      <FieldError>That username is taken.</FieldError>
    </Field>
    <Field orientation="horizontal">
      <Checkbox id="newsletter" />
      <FieldLabel>Email me the weekly digest</FieldLabel>
    </Field>
  </FieldGroup>
</Fieldset>
```

Use arene controls inside `Field` to inherit labels, descriptions, validation and disabled state.

## Composition

### Field

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

```text
Field
├── FieldLabel
├── Input / Checkbox
├── FieldDescription
└── FieldError
```

### FieldGroup

Groups related fields. Put a `FieldSeparator` between sections that need one.

```text
FieldGroup
├── Field
├── FieldSeparator
└── Field
```

### Fieldset

A `fieldset` element with a legend and a description. It usually holds a
`FieldGroup`.

```text
Fieldset
├── FieldsetLegend
├── FieldDescription
└── FieldGroup
    ├── Field
    └── Field
```

## Anatomy

```tsx
<Field>
  <FieldLabel>Label</FieldLabel>
  {/* Input, Checkbox, etc. */}
  <FieldDescription>Helper text, when the field needs it.</FieldDescription>
  <FieldError>Shown when the value is invalid.</FieldError>
</Field>
```

- `Field` is the wrapper for a single field. It publishes its `orientation`,
  `invalid` and `disabled` state to the parts inside it.
- `FieldContent` is a column that groups the label and description beside a
  control. You do not need it if there is no description.
- Wrap related fields with `FieldGroup`, and use `Fieldset` with `FieldsetLegend`
  for semantic grouping.

## Form

See [React Hook Form](https://www.arene.style/docs/forms/react-hook-form) for building a form with
`Field`, schema validation and per-field errors.

## Input

```tsx
import { Field, FieldDescription, FieldGroup, FieldLabel } from "@/components/ui/field"
import { Fieldset } from "@/components/ui/fieldset"
import { Input } from "@/components/ui/input"
import { widths } from "@/theme/widths"

export default function FieldInput() {
  return (
    <Fieldset xstyle={widths.xs}>
      <FieldGroup>
        <Field>
          <FieldLabel>Username</FieldLabel>
          <Input id="field-input-username" type="text" placeholder="turing" />
          <FieldDescription>Other researchers find you by this name.</FieldDescription>
        </Field>
        <Field>
          <FieldLabel>Password</FieldLabel>
          <FieldDescription>Use 8 characters or more.</FieldDescription>
          <Input id="field-input-password" type="password" placeholder="••••••••" />
        </Field>
      </FieldGroup>
    </Fieldset>
  )
}
```

## Fieldset

Use `Fieldset` and `FieldsetLegend` to group fields under a heading. `FieldsetLegend`
takes `variant="label"` to size the heading like a label, for a fieldset nested
inside a form.

```tsx
import * as stylex from "@stylexjs/stylex"
import { Field, FieldDescription, FieldGroup, FieldLabel } from "@/components/ui/field"
import { FieldsetLegend, Fieldset } from "@/components/ui/fieldset"
import { Input } from "@/components/ui/input"
import { space } from "@/theme/tokens.stylex"
import { widths } from "@/theme/widths"

const styles = stylex.create({
  columns: { display: "grid", gridTemplateColumns: "repeat(2, minmax(0, 1fr))", gap: space.s4 },
})

export default function FieldFieldset() {
  return (
    <Fieldset xstyle={widths.sm}>
      <FieldsetLegend>Lab Address</FieldsetLegend>
      <FieldDescription>Samples and equipment ship to this address.</FieldDescription>
      <FieldGroup>
        <Field>
          <FieldLabel>Street Address</FieldLabel>
          <Input id="field-fieldset-street" type="text" placeholder="14 Gauss Lane" />
        </Field>
        <div {...stylex.props(styles.columns)}>
          <Field>
            <FieldLabel>City</FieldLabel>
            <Input id="field-fieldset-city" type="text" placeholder="Göttingen" />
          </Field>
          <Field>
            <FieldLabel>Postal Code</FieldLabel>
            <Input id="field-fieldset-zip" type="text" placeholder="37073" />
          </Field>
        </div>
      </FieldGroup>
    </Fieldset>
  )
}
```

## Checkbox

Use `orientation="horizontal"` to put the control before the label. Wrap the
label and a description in `FieldContent` when a row has both.

```tsx
import * as stylex from "@stylexjs/stylex"
import { Checkbox } from "@/components/ui/checkbox"
import {
  Field,
  FieldContent,
  FieldDescription,
  FieldGroup,
  FieldLabel,
  FieldSeparator,
} from "@/components/ui/field"
import { FieldsetLegend, Fieldset } from "@/components/ui/fieldset"
import { width } from "@/theme/tokens.stylex"

const styles = stylex.create({
  group: { maxWidth: width.xs },
})

const items = [
  { id: "raw-data", label: "Raw data" },
  { id: "plots", label: "Plots" },
  { id: "lab-notes", label: "Lab notes" },
  { id: "instrument-logs", label: "Instrument logs" },
]

export default function FieldCheckbox() {
  return (
    <FieldGroup xstyle={styles.group}>
      <Fieldset>
        <FieldsetLegend variant="label">Include in the export</FieldsetLegend>
        <FieldDescription>Choose what goes into the exported notebook.</FieldDescription>
        <FieldGroup gap={3}>
          {items.map((item) => (
            <Field key={item.id} orientation="horizontal">
              <Checkbox id={`export-${item.id}`} />
              <FieldLabel>{item.label}</FieldLabel>
            </Field>
          ))}
        </FieldGroup>
      </Fieldset>
      <FieldSeparator />
      <Field orientation="horizontal">
        <Checkbox id="export-archive" defaultChecked />
        <FieldContent>
          <FieldLabel>Keep a copy in the archive</FieldLabel>
          <FieldDescription>
            Each export is also saved to the lab archive, where the whole team can open it later.
          </FieldDescription>
        </FieldContent>
      </Field>
    </FieldGroup>
  )
}
```

## Choice card

Wrap a `Field` inside a `FieldLabel` to make the whole card select the control.
Pass `checked` to the label as well as the control.

```tsx
"use client"

import { useState } from "react"
import * as stylex from "@stylexjs/stylex"
import { Checkbox } from "@/components/ui/checkbox"
import {
  Field,
  FieldContent,
  FieldDescription,
  FieldGroup,
  FieldLabel,
  FieldTitle,
} from "@/components/ui/field"
import { FieldsetLegend, Fieldset } from "@/components/ui/fieldset"
import { width } from "@/theme/tokens.stylex"

const styles = stylex.create({
  group: { maxWidth: width.xs },
})

const environments = [
  { id: "cluster", title: "Shared cluster", description: "Queue jobs on the lab's GPU nodes." },
  { id: "workstation", title: "Workstation", description: "Run jobs on the machine at your desk." },
]

export default function FieldChoiceCard() {
  const [selected, setSelected] = useState(["cluster"])

  return (
    <FieldGroup xstyle={styles.group}>
      <Fieldset>
        <FieldsetLegend variant="label">Run Location</FieldsetLegend>
        <FieldDescription>Choose where your simulations can run.</FieldDescription>
        <FieldGroup gap={3}>
          {environments.map((environment) => {
            const checked = selected.includes(environment.id)
            return (
              <FieldLabel
                key={environment.id}
                htmlFor={`compute-${environment.id}`}
                checked={checked}
              >
                <Field orientation="horizontal">
                  <FieldContent>
                    <FieldTitle>{environment.title}</FieldTitle>
                    <FieldDescription>{environment.description}</FieldDescription>
                  </FieldContent>
                  <Checkbox
                    id={`compute-${environment.id}`}
                    checked={checked}
                    onCheckedChange={(next) =>
                      setSelected(
                        next
                          ? [...selected, environment.id]
                          : selected.filter((id) => id !== environment.id),
                      )
                    }
                  />
                </Field>
              </FieldLabel>
            )
          })}
        </FieldGroup>
      </Fieldset>
    </FieldGroup>
  )
}
```

> **Note**
>
> The label draws the selected frame from its own `checked` prop, not from the
> control inside it. StyleX cannot select a parent by a child's state, and the
> `:has()` that would is off arene's browser floor. The choice card is therefore
> a controlled pattern.

## Field group

Stack fields with `FieldGroup`. Use `FieldSeparator` to divide them, and `gap`
to tighten a list of checkboxes.

```tsx
import * as stylex from "@stylexjs/stylex"
import { Checkbox } from "@/components/ui/checkbox"
import { Field, FieldDescription, FieldGroup, FieldLabel, FieldSeparator } from "@/components/ui/field"
import { FieldsetLegend, Fieldset } from "@/components/ui/fieldset"
import { width } from "@/theme/tokens.stylex"

const styles = stylex.create({
  group: { maxWidth: width.xs },
})

export default function FieldGroupDemo() {
  return (
    <FieldGroup xstyle={styles.group}>
      <Fieldset>
        <FieldsetLegend variant="label">Experiments</FieldsetLegend>
        <FieldDescription>
          Get notified when a long run finishes, such as a simulation or a parameter sweep.
        </FieldDescription>
        <FieldGroup gap={3}>
          <Field orientation="horizontal" disabled>
            <Checkbox id="notify-push" defaultChecked />
            <FieldLabel>Push notifications</FieldLabel>
          </Field>
        </FieldGroup>
      </Fieldset>
      <FieldSeparator />
      <Fieldset>
        <FieldsetLegend variant="label">Comments</FieldsetLegend>
        <FieldDescription>
          Get notified when someone replies to an entry you wrote.{" "}
          <a href="https://example.com/comments">Manage comments</a>
        </FieldDescription>
        <FieldGroup gap={3}>
          <Field orientation="horizontal">
            <Checkbox id="notify-push-tasks" />
            <FieldLabel>Push notifications</FieldLabel>
          </Field>
          <Field orientation="horizontal">
            <Checkbox id="notify-email-tasks" />
            <FieldLabel>Email notifications</FieldLabel>
          </Field>
        </FieldGroup>
      </Fieldset>
    </FieldGroup>
  )
}
```

## Responsive layout

- **Vertical fields.** The default stacks the label, the control and the helper text.
- **Horizontal fields.** Set `orientation="horizontal"` to put the label and
  control side by side. Pair it with `FieldContent` to keep a description
  aligned under the label.
- **Responsive fields.** Set `orientation="responsive"` to stack on a narrow
  `FieldGroup` and form a row once the group is `28rem` wide. Give a control
  that stretches, such as `Input`, `xstyle={fieldStyles.control}` so its
  width becomes `auto` when the row forms.

```tsx
import * as stylex from "@stylexjs/stylex"
import { Button } from "@/components/ui/button"
import {
  Field,
  FieldContent,
  FieldDescription,
  FieldGroup,
  FieldLabel,
  fieldStyles,
} from "@/components/ui/field"
import { FieldsetLegend, Fieldset } from "@/components/ui/fieldset"
import { Input } from "@/components/ui/input"
import { widths } from "@/theme/widths"

export default function FieldResponsive() {
  return (
    <form {...stylex.props(widths.lg)} onSubmit={(event) => event.preventDefault()}>
      <Fieldset>
        <FieldsetLegend>Profile</FieldsetLegend>
        <FieldDescription>This is how other researchers see you.</FieldDescription>
        <FieldGroup>
          <Field orientation="responsive">
            <FieldContent>
              <FieldLabel>Name</FieldLabel>
              <FieldDescription>Your name as it appears on your papers</FieldDescription>
            </FieldContent>
            <Input
              id="profile-name"
              placeholder="Ada Lovelace"
              required
              xstyle={fieldStyles.control}
            />
          </Field>
          <Field orientation="responsive">
            <Button type="submit">Submit</Button>
            <Button type="button" variant="outline">
              Cancel
            </Button>
          </Field>
        </FieldGroup>
      </Fieldset>
    </form>
  )
}
```

> **Note**
>
> A responsive field measures the nearest `FieldGroup`, not the viewport. Outside
> a group there is no container to query and the field stays vertical.

## Validation and errors

- Set `invalid` on `Field` to turn the label and error red.
- Controls inherit validation and disabled state from `Field`.
- Render `FieldError` after the control, or inside `FieldContent`, so the
  message lines up with the field. Base UI shows it when the field is invalid.

```tsx
import * as stylex from "@stylexjs/stylex"
import { Field, FieldDescription, FieldError, FieldLabel } from "@/components/ui/field"
import { Input } from "@/components/ui/input"
import { width } from "@/theme/tokens.stylex"

const styles = stylex.create({
  field: { maxWidth: width.xs },
})

export default function FieldInvalid() {
  return (
    <Field invalid xstyle={styles.field}>
      <FieldLabel>Email</FieldLabel>
      <Input id="field-invalid-email" type="email" defaultValue="evil@rabbit" />
      <FieldDescription>We only use it to send your receipt.</FieldDescription>
      <FieldError>Enter a valid email address.</FieldError>
    </Field>
  )
}
```

```tsx
<Field invalid>
  <FieldLabel>Email</FieldLabel>
  <Input id="email" type="email" />
  <FieldError>Enter a valid email address.</FieldError>
</Field>
```

`FieldError` also takes an `errors` array, the shape a form library produces.
One message renders as text and several as a list, with duplicates removed.

```tsx
<FieldError errors={[fieldState.error]} />
```

## Inherited state

Set `invalid` and `disabled` on `Field` to style and disable its control.

```tsx
import { Field, FieldGroup, FieldLabel, FieldDescription } from "@/components/ui/field"
import { Input } from "@/components/ui/input"
import { Textarea } from "@/components/ui/textarea"
import { Checkbox } from "@/components/ui/checkbox"
import { Switch } from "@/components/ui/switch"
import { RadioGroup, RadioGroupItem } from "@/components/ui/radio-group"
import {
  Select,
  SelectTrigger,
  SelectValue,
  SelectContent,
  SelectItem,
  SelectGroup,
} from "@/components/ui/select"
import { Slider } from "@/components/ui/slider"
import { InputOTP, InputOTPSlot } from "@/components/ui/input-otp"
import { InputGroup, InputGroupAddon, InputGroupText } from "@/components/ui/input-group"
import { Combobox, ComboboxInput } from "@/components/ui/combobox"
import { VStack } from "@/components/ui/stack"

export default function FieldStates() {
  return (
    <VStack width="100%" maxWidth="24rem" gap={5}>
      {[false, true].map((disabled) => (
        <FieldGroup key={String(disabled)}>
          <Field invalid disabled={disabled}>
            <FieldLabel>Email</FieldLabel>
            <Input placeholder="Email" />
            <FieldDescription>{disabled ? "Disabled and invalid" : "Invalid"}</FieldDescription>
          </Field>
          <Field invalid disabled={disabled}>
            <FieldLabel>Message</FieldLabel>
            <Textarea placeholder="Message" />
          </Field>
          <Field invalid disabled={disabled}>
            <FieldLabel>Agree to policy</FieldLabel>
            <Checkbox />
          </Field>
          <Field invalid disabled={disabled}>
            <FieldLabel>Notifications</FieldLabel>
            <Switch />
          </Field>
          <Field invalid disabled={disabled}>
            <FieldLabel>Plan</FieldLabel>
            <RadioGroup>
              <RadioGroupItem value="free" aria-label="Free" />
              <RadioGroupItem value="pro" aria-label="Pro" />
            </RadioGroup>
          </Field>
          <Field invalid disabled={disabled}>
            <FieldLabel>Element</FieldLabel>
            <Select>
              <SelectTrigger>
                <SelectValue />
              </SelectTrigger>
              <SelectContent>
                <SelectGroup>
                  <SelectItem value="hydrogen">Hydrogen</SelectItem>
                </SelectGroup>
              </SelectContent>
            </Select>
          </Field>
          <Field invalid disabled={disabled}>
            <FieldLabel>Volume</FieldLabel>
            <Slider defaultValue={25} />
          </Field>
          <Field invalid disabled={disabled}>
            <FieldLabel>Code</FieldLabel>
            <InputOTP length={2}>
              <InputOTPSlot />
              <InputOTPSlot />
            </InputOTP>
          </Field>
          <Field invalid disabled={disabled}>
            <FieldLabel>Website</FieldLabel>
            <InputGroup>
              <Input />
              <InputGroupAddon>
                <InputGroupText>https://</InputGroupText>
              </InputGroupAddon>
            </InputGroup>
          </Field>
          <Field invalid disabled={disabled}>
            <FieldLabel>Framework</FieldLabel>
            <Combobox items={["React", "Vue"]}>
              <ComboboxInput />
            </Combobox>
          </Field>
        </FieldGroup>
      ))}
    </VStack>
  )
}
```

## Native validation

Use `validate` or native attributes such as `required`, then render `FieldError`.

```tsx
import * as stylex from "@stylexjs/stylex"
import { Field, FieldLabel, FieldError, FieldValidity } from "@/components/ui/field"
import { Textarea } from "@/components/ui/textarea"

const styles = stylex.create({ field: { width: "20rem" } })

export default function FieldValidation() {
  return (
    <Field
      name="message"
      validationMode="onBlur"
      validate={(value) => (String(value).length < 20 ? "Write at least 20 characters." : null)}
      xstyle={styles.field}
    >
      <FieldLabel>Message</FieldLabel>
      <Textarea required placeholder="Type a message, then leave the field" />
      <FieldError />
      <FieldValidity>
        {({ validity }) => (validity.valid === true ? <output>Message ready.</output> : null)}
      </FieldValidity>
    </Field>
  )
}
```

## Accessibility

- `Fieldset` and `FieldsetLegend` keep related controls grouped for keyboard and
  assistive tech users.
- `FieldLabel` and `FieldDescription` associate automatically with the control.
- `FieldError` renders `role="alert"`, so a message that appears is announced.
- Apply `FieldSeparator` sparingly. Each one is a section boundary a screen
  reader stops at.

## Grouped choices

Wrap each checkbox or radio and its label in `FieldItem` to give it a separate label association within one field. See [Checkbox Group](https://www.arene.style/docs/components/checkbox-group).

## API reference

Pass `render` to replace a part's element or compose it with another component.

`Field`, `FieldLabel`, `FieldDescription` and `FieldError` wrap the corresponding [Base UI Field parts](https://base-ui.com/react/components/field). Styled parts accept `xstyle`, `className`, inline `style` and `render`. Layout parts keep their native attributes.

### Field

| Prop          | Type                                         | Default      |
| ------------- | -------------------------------------------- | ------------ |
| `orientation` | `"vertical" \| "horizontal" \| "responsive"` | `"vertical"` |
| `invalid`     | `boolean`                                    | —            |
| `disabled`    | `boolean`                                    | `false`      |

`Field` passes `disabled` to the control and dims the label and title. It passes `invalid`, `name`, `validate`, `validationMode`, `dirty` and `touched` to Base UI.

See [Fieldset](https://www.arene.style/docs/components/fieldset) for `Fieldset` and `FieldsetLegend`.

### FieldGroup

| Prop  | Type          | Default |
| ----- | ------------- | ------- |
| `gap` | `SpacingStep` | `5`     |

### FieldLabel

| Prop       | Type      | Default |
| ---------- | --------- | ------- |
| `checked`  | `boolean` | —       |
| `disabled` | `boolean` | —       |

`checked` draws the choice-card frame and only applies when the label wraps a
`Field`. `disabled` falls back to the enclosing field's value.

### FieldError

| Prop     | Type                                       | Default |
| -------- | ------------------------------------------ | ------- |
| `errors` | `Array<{ message?: string } \| undefined>` | —       |
| `match`  | `boolean \| keyof ValidityState`           | —       |

Children take precedence over `errors`. With neither, Base UI displays the validation message. Pass `match` to select a validity condition. `FieldValidity` exposes Base UI validity through a render function.

### fieldStyles

The style maps behind the component. Spread them onto any element.

| Key            | What it is                                                 |
| -------------- | ---------------------------------------------------------- |
| `field`        | The row or column: flex, full width, the gap between parts |
| `orientations` | `vertical`, `horizontal` and `responsive` direction maps   |
| `invalid`      | The destructive text colour                                |
| `control`      | Full width that becomes `auto` once a responsive row forms |
| `card`         | The choice-card panel: raised surface, radius, inset       |
| `cardChecked`  | The card's selected edge                                   |
| `cardFocused`  | The card's focus ring, painted without a pseudo-class      |
| `description`  | Muted small text                                           |
| `error`        | Destructive small text                                     |

`card` is the panel alone. Merge `cardChecked` and `cardFocused` over it for the
selected edge and the focus ring. `cardFocused` is `states.ring` from
`theme/states.ts` with the card's lift kept under it, and has no pseudo-class:
the card tracks focus itself, from a focus event that bubbles up from the
control inside it.

### FieldItem

`FieldItem` accepts Base UI `Field.Item` props, including `disabled` and `render`, plus `xstyle`, `className`, and inline `style`. It adds no layout styles.

### Data attributes

| Attribute                                                                                                  | On                 | Effect                                      |
| ---------------------------------------------------------------------------------------------------------- | ------------------ | ------------------------------------------- |
| `data-slot="field-item"`                                                                                   | individual choice  | Label and description scope                 |
| `data-slot="field"`                                                                                        | the field          | Targets the field from a parent             |
| `data-orientation`                                                                                         | the field          | Mirrors `orientation`                       |
| `data-valid`, `data-invalid`, `data-disabled`, `data-dirty`, `data-touched`, `data-filled`, `data-focused` | the field          | Base UI validity and disabled state         |
| `data-slot="field-group"`                                                                                  | the group          | The container a responsive field queries    |
| `data-slot="field-content"`                                                                                | the text column    |                                             |
| `data-slot="field-label"`                                                                                  | the label          | `data-checked` present on a selected card   |
| `data-slot="field-title"`                                                                                  | the title          |                                             |
| `data-slot="field-description"`                                                                            | the description    | Where `interop.css` styles a link inside it |
| `data-slot="field-separator"`                                                                              | the separator      | `data-content` present when it carries text |
| `data-slot="field-separator-line"`                                                                         | the rule           | Renders `role="separator"`                  |
| `data-slot="field-separator-content"`                                                                      | the text on a rule |                                             |
| `data-slot="field-error"`                                                                                  | the error          | Renders `role="alert"`                      |
