Field

Installation#

pnpmnpmyarnbun
pnpm dlx shadcn@latest add @force-ui-svelte/field
Copy

Usage#

Copy<script lang="ts">
  import * as Field from "$lib/components/ui/field/index.js";
</script>

Copy<Field.Set>
  <Field.Legend>Profile</Field.Legend>
  <Field.Description>This appears on invoices and emails.</Field.Description>
  <Field.Group>
    <Field.Field>
      <Field.Label for="name">Full name</Field.Label>
      <Input id="name" autocomplete="off" placeholder="Evil Rabbit" />
      <Field.Description
        >This appears on invoices and emails.</Field.Description
      >
    </Field.Field>
    <Field.Field>
      <Field.Label for="username">Username</Field.Label>
      <Input id="username" autoComplete="off" aria-invalid />
      <Field.Error>Choose another username.</Field.Error>
    </Field.Field>
    <Field.Field orientation="horizontal">
      <Switch id="newsletter" />
      <Field.Label for="newsletter">Subscribe to the newsletter</Field.Label>
    </Field.Field>
  </Field.Group>
</Field.Set>

Composition#

Field.Field#

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

CopyField.Field
├── Field.Label
├── Input / Textarea / Switch / Select
├── Field.Description
└── Field.Error

Field.Group#

Related fields in one group. Use Field.Separator between sections when needed.

CopyField.Group
├── Field.Field
│   ├── Field.Label
│   ├── Input / Textarea / Switch / Select
│   ├── Field.Description
│   └── Field.Error
├── Field.Separator
└── Field.Field
    ├── Field.Label
    └── Input / Textarea / Switch / Select

Field.Set#

Semantic grouping with a legend and description, usually containing a Field.Group.

CopyField.Set
├── Field.Legend
├── Field.Description
└── Field.Group
    ├── Field.Field
    │   ├── Field.Label
    │   ├── Input / Textarea / Switch / Select
    │   ├── Field.Description
    │   └── Field.Error
    └── Field.Field
        ├── Field.Label
        └── Input / Textarea / Switch / Select

Anatomy#

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

Copy<Field.Field>
  <Field.Label for="input-id">Label</Field.Label>
  <Field.Description>Optional helper text.</Field.Description>
  <Field.Error>Validation message.</Field.Error>
</Field.Field>

• Field.Field is the core wrapper for a single field.
• Field.Content is a flex column that groups label and description. Not required if you have no description.
• Wrap related fields with Field.Group, and use Field.Set with Field.Legend for semantic grouping.

Form#

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

Examples#

Input#

Textarea#

Select#

Slider#

Fieldset#

Checkbox#

Radio#

Switch#

Choice Card#

Wrap Field components inside Field.Label to create selectable field groups. This works with RadioItem, Checkbox and Switch components.

Field Group#

Stack Field.Field components with Field.Group. Add Field.Separator to divide them.

RTL#

To enable RTL support in Force UI, see the RTL configuration guide.

Responsive Layout#

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

Validation and Errors#

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

Copy<Field.Field data-invalid>
  <Field.Label for="email">Email</Field.Label>
  <Input id="email" type="email" aria-invalid />
  <Field.Error>Enter a valid email address.</Field.Error>
</Field.Field>

Accessibility#

• Field.Set and Field.Legend keep related controls grouped for keyboard and assistive tech users.
• Field.Field outputs role="group" so nested controls inherit labeling from Field.Label and Field.Legend when combined.
• Apply Field.Separator sparingly to ensure screen readers encounter clear section boundaries.

API Reference#

Field.Set#

Container that renders a semantic fieldset with spacing presets.

Copy<Field.Set>
  <Field.Legend>Delivery</Field.Legend>
  <Field.Group>{/* Fields */}</Field.Group>
</Field.Set>

Field.Legend#

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

Copy<Field.Legend variant="label">Notification Preferences</Field.Legend>

The Field.Legend has two variants: legend and label. The label variant applies label sizing and alignment. Handy if you have nested Field.Set.

Field.Group#

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

Copy<Field.Group class="@container/field-group flex flex-col gap-6">
  <Field.Field>{/* ... */}</Field.Field>
  <Field.Field>{/* ... */}</Field.Field>
</Field.Group>

Field.Field#

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

Copy<Field.Field orientation="horizontal">
  <Field.Label for="remember">Remember me</Field.Label>
  <Switch id="remember" />
</Field.Field>

Field.Content#

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

Copy<Field.Field>
  <Checkbox id="notifications" />
  <Field.Content>
    <Field.Label for="notifications">Notifications</Field.Label>
    <Field.Description>Email, SMS, and push options.</Field.Description>
  </Field.Content>
</Field.Field>

Field.Label#

Label styled for both direct inputs and nested Field.Field children.

Copy<Field.Label for="email">Email</Field.Label>

Field.Title#

Renders a title with label styling inside Field.Content.

Copy<Field.Content>
  <Field.Title>Enable Touch ID</Field.Title>
  <Field.Description>Unlock your device faster.</Field.Description>
</Field.Content>

Field.Description#

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

Copy<Field.Description>We never share your email with anyone.</Field.Description>

Field.Separator#

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

Copy<Field.Separator>Or continue with</Field.Separator>

Field.Error#

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

Copy<Field.Error errors={errors.username} />

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

Field.Error 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.