Field

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

Card Details

We charge this card on the first of each month

The 16 digits on the front of the card

Invoice Address

Where we send the monthly invoice for your lab

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

pnpm dlx shadcn@latest add @arene/field

Needs the arene setup first. Also adds Label, Separator and Stack.

Use Fieldset to group related fields.

Usage

import {
  Field,
  FieldContent,
  FieldDescription,
  FieldError,
  FieldGroup,
  FieldLabel,
  FieldSeparator,
  FieldTitle,
} from "@/components/ui/field"
import { FieldsetLegend, Fieldset } from "@/components/ui/fieldset"
<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.

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

FieldGroup

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

FieldGroup
├── Field
├── FieldSeparator
└── Field

Fieldset

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

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

Anatomy

<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 for building a form with Field, schema validation and per-field errors.

Input

Other researchers find you by this name.

Use 8 characters or more.

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.

Lab Address

Samples and equipment ship to this address.

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.

Include in the export

Choose what goes into the exported notebook.

Each export is also saved to the lab archive, where the whole team can open it later.

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.

Run Location

Choose where your simulations can run.

"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>
  )
}

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.

Experiments

Get notified when a long run finishes, such as a simulation or a parameter sweep.

Comments

Get notified when someone replies to an entry you wrote. Manage comments

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.
Profile

This is how other researchers see you.

Your name as it appears on your papers

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>
  )
}

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.

We only use it to send your receipt.

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>
  )
}
<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.

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

Inherited state

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

Invalid

https://

Disabled and invalid

https://
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.

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.

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. Styled parts accept xstyle, className, inline style and render. Layout parts keep their native attributes.

Field

PropTypeDefault
orientation"vertical" | "horizontal" | "responsive""vertical"
invalidboolean—
disabledbooleanfalse

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 for Fieldset and FieldsetLegend.

FieldGroup

PropTypeDefault
gapSpacingStep5

FieldLabel

PropTypeDefault
checkedboolean—
disabledboolean—

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

PropTypeDefault
errorsArray<{ message?: string } | undefined>—
matchboolean | 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.

KeyWhat it is
fieldThe row or column: flex, full width, the gap between parts
orientationsvertical, horizontal and responsive direction maps
invalidThe destructive text colour
controlFull width that becomes auto once a responsive row forms
cardThe choice-card panel: raised surface, radius, inset
cardCheckedThe card's selected edge
cardFocusedThe card's focus ring, painted without a pseudo-class
descriptionMuted small text
errorDestructive 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

AttributeOnEffect
data-slot="field-item"individual choiceLabel and description scope
data-slot="field"the fieldTargets the field from a parent
data-orientationthe fieldMirrors orientation
data-valid, data-invalid, data-disabled, data-dirty, data-touched, data-filled, data-focusedthe fieldBase UI validity and disabled state
data-slot="field-group"the groupThe container a responsive field queries
data-slot="field-content"the text column
data-slot="field-label"the labeldata-checked present on a selected card
data-slot="field-title"the title
data-slot="field-description"the descriptionWhere interop.css styles a link inside it
data-slot="field-separator"the separatordata-content present when it carries text
data-slot="field-separator-line"the ruleRenders role="separator"
data-slot="field-separator-content"the text on a rule
data-slot="field-error"the errorRenders role="alert"