Field

Field connects one form control with its label, description, validation state, and error message.

Purpose

Field connects one form control with its label, description, validation state, and error message.

Labeled control

Used for workspace notifications.

import { Field, FieldDescription, FieldError, FieldLabel } from "@/components/ui/field";
import { Input } from "@/components/ui/input";

export function Example() {
  return (
    <Field name="email">
      <FieldLabel>Email</FieldLabel>
      <Input type="email" />
      <FieldDescription>Used for notifications.</FieldDescription>
      <FieldError />
    </Field>
  );
}

Installation

With the Siteplane registry alias configured, add the component and import the installed source from your app.

CLI

pnpm dlx shadcn@4.16.1 add @siteplane/field

Import

import { Field, FieldControl, FieldDescription, FieldError, FieldItem, FieldLabel, FieldValidity } from "@/components/ui/field";

Need the machine-readable source metadata? View registry JSON.

Usage

Use Field for every visible form control. It couples labels, descriptions and errors with the control automatically.

import { Field, FieldDescription, FieldError, FieldLabel } from "@/components/ui/field";
import { Input } from "@/components/ui/input";

export function Example() {
  return (
    <Field name="email">
      <FieldLabel>Email</FieldLabel>
      <Input type="email" />
      <FieldDescription>Used for notifications.</FieldDescription>
      <FieldError />
    </Field>
  );
}

Examples

States, control variants, validation and practical field patterns are compositions of the same primitive.

Disabled

Billing email

Only workspace owners can change this address.

<Field disabled>
  <FieldLabel>Billing email</FieldLabel>
  <Input defaultValue="finance@ui.siteplane.io" disabled />
  <FieldDescription>
    Only workspace owners can change this address.
  </FieldDescription>
</Field>

Invalid

Work email

Please enter a valid email address.

<Field>
  <FieldLabel>Work email</FieldLabel>
  <Input aria-invalid defaultValue="not-an-email" />
  <FieldError match>Please enter a valid email address.</FieldError>
</Field>

With select

Region

Controls where data is stored.

<Field>
  <FieldLabel>Region</FieldLabel>
  <Select defaultValue="eu-central" items={regions}>
    <SelectTrigger aria-label="Region" className="w-full">
      <SelectValue />
    </SelectTrigger>
    <SelectPopup>
      {regions.map(({ label, value }) => (
        <SelectItem key={value} value={value}>{label}</SelectItem>
      ))}
    </SelectPopup>
  </Select>
  <FieldDescription>Controls where data is stored.</FieldDescription>
</Field>

With switch

Enable weekly digest

Sends a summary to your team every Monday.

<Field>
  <FieldLabel className="cursor-pointer">
    <Switch defaultChecked />
    Enable weekly digest
  </FieldLabel>
  <FieldDescription>
    Sends a summary to your team every Monday.
  </FieldDescription>
</Field>

With textarea

Release notes

Markdown is supported.

<Field>
  <FieldLabel>Release notes</FieldLabel>
  <Textarea placeholder="What changed?" />
  <FieldDescription>Markdown is supported.</FieldDescription>
</Field>

Required

<Form onSubmit={onSubmit}>
  <Field name="slug">
    <FieldLabel>Project slug</FieldLabel>
    <Input placeholder="my-project" required />
    <FieldError match="valueMissing">This field is required.</FieldError>
  </Field>
  <Button loading={loading} type="submit">Submit</Button>
</Form>

Live validation

FieldControl and FieldValidity expose the live validity state while typing.

Display name

Looks good.

<Field
  validate={(value) =>
    String(value).length < 3 ? "At least 3 characters." : null
  }
  validationMode="onChange"
>
  <FieldLabel id={labelId}>Display name</FieldLabel>
  <FieldControl aria-labelledby={labelId} defaultValue="mo" />
  <FieldValidity>
    {(state) => (
      <FieldDescription>
        {state.validity.valid === false ? "Still too short." : "Looks good."}
      </FieldDescription>
    )}
  </FieldValidity>
  <FieldError />
</Field>

Description and error

API token name

A descriptive name helps when revoking tokens later.

The name cannot be empty.

<Field>
  <FieldLabel>API token name</FieldLabel>
  <Input aria-invalid placeholder="e.g. CI deploy" />
  <FieldDescription>
    A descriptive name helps when revoking tokens later.
  </FieldDescription>
  <FieldError match>The name cannot be empty.</FieldError>
</Field>

Form integration

<Form onSubmit={onSubmit}>
  <Field name="workspace">
    <FieldLabel>Workspace name</FieldLabel>
    <Input defaultValue="plane" placeholder="Acme Inc." />
    <FieldDescription>Visible to every member.</FieldDescription>
  </Field>
  <Button loading={loading} type="submit">Submit</Button>
</Form>

Settings row

Two-factor auth

Require a second factor when signing in.

<Field>
  <label
    className="flex w-full cursor-pointer items-start justify-between gap-4"
    htmlFor={controlId}
  >
    <span className="grid min-w-0 gap-1">
      <span className="font-medium text-sm leading-5" id={labelId}>
        Two-factor auth
      </span>
      <FieldDescription id={descriptionId}>
        Require a second factor when signing in.
      </FieldDescription>
    </span>
    <Switch
      aria-describedby={descriptionId}
      aria-labelledby={labelId}
      defaultChecked
      id={controlId}
    />
  </label>
</Field>

Inline field

Seats

<Field>
  <div className="flex w-full items-center gap-3">
    <FieldLabel className="shrink-0" id={labelId}>Seats</FieldLabel>
    <Input
      aria-labelledby={labelId}
      className="max-w-28"
      defaultValue="5"
      inputMode="numeric"
    />
  </div>
</Field>

Field item

FieldItem groups a control with its own text inside a Field.

Notifications

Choose which updates reach your inbox.