Preview

Installation

npx sigma-ui@latest add field

Usage

<script setup lang="ts">
import { Field, FieldDescription, FieldError, FieldGroup, FieldLabel } from '@/components/ui/field';
import { Input } from '@/components/ui/input';
</script>

<template>
  <FieldGroup>
    <Field>
      <FieldLabel for="name">Name</FieldLabel>
      <Input id="name" />
      <FieldDescription>Shown on your profile.</FieldDescription>
    </Field>
  </FieldGroup>
</template>

Field wraps one control with its label, description, and error. Set orientation to vertical, horizontal, or responsive.

• FieldLabel labels the control. Wrap a whole Field with it to build a selectable card.
• FieldDescription is helper text under the control or inside a FieldSet.
• FieldError shows error text from the errors prop or the default slot.
• FieldContent stacks a label and a description next to a checkbox, radio, or switch.
• FieldTitle is a title that is not tied to a single control.
• FieldSet and FieldLegend group related fields in a fieldset.
• FieldGroup stacks fields and is the container the responsive orientation measures.
• FieldSeparator divides groups, with optional text.

Responsive orientation

orientation="responsive" stacks the label above the control in narrow containers and places them side by side when the parent FieldGroup is at least 28rem wide. It uses a container query, so it reacts to the width of the form, not the viewport.

Examples

Validation

Set invalid on Field and pass messages to FieldError. errors accepts strings or objects with a message, so validation issues from libraries such as Zod or VeeValidate can be passed directly. Duplicates and empty values are skipped.

Choice card

Wrap a Field in FieldLabel to make the whole card clickable. The card is highlighted when the control inside it is checked.

Responsive

API Reference

Field

Props

Prop	Type	Default
orientation Layout of the label and the control. responsive switches from vertical to horizontal when the parent FieldGroup is wide enough.	"vertical" | "horizontal" | "responsive" | null	"vertical"
invalid Marks the field as invalid and colors its label and description.	boolean	false
disabled Dims the label to match a disabled control.	boolean	false

Slots

Slot	Scope
default Field parts: FieldLabel, the control, FieldDescription, and FieldError.	-

FieldContent

Slots

Slot	Scope
default FieldLabel or FieldTitle with a FieldDescription, placed next to a checkbox, radio, or switch.	-

FieldDescription

Slots

Slot	Scope
default Helper text. Links inside it are underlined.	-

FieldError

Props

Prop	Type	Default
errors Error messages to show. Accepts strings or objects with a message, such as validation library issues. Duplicates are removed.	FieldErrorItem[]	-

Slots

Slot	Scope
default Custom error content. Replaces the errors list.	-

FieldGroup

Slots

Slot	Scope
default Field, FieldSet, and FieldSeparator components.	-

FieldLabel

Props

Prop	Type	Default
for The id of the element the label is associated with.	string	-
asChild Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details.	boolean	-
as The element or component this component should render as. Can be overwritten by asChild.	AsTag | Component	"div"

Slots

Slot	Scope
default Label text. Wrap a whole Field to turn it into a selectable card.	-

FieldLegend

Props

Prop	Type	Default
variant legend renders a section heading, label matches the size of a field label.	"label" | "legend"	"legend"

Slots

Slot	Scope
default Legend text of the FieldSet.	-

FieldSeparator

Slots

Slot	Scope
default Optional text shown in the middle of the line, such as "Or continue with".	-

FieldSet

Slots

Slot	Scope
default A FieldLegend, an optional FieldDescription, and a FieldGroup.	-

FieldTitle

Slots

Slot	Scope
default Title text. Use instead of FieldLabel when the title is not tied to a single control.	-

Accessibility

Field renders role="group". FieldSet renders a native fieldset, which also disables every control inside it when it has the disabled attribute. FieldError renders role="alert".

Set the for attribute of FieldLabel to the id of the control. Set aria-invalid on the control together with invalid on Field, so screen readers announce the error state.

Key	Description
Tab	Moves focus to the control inside the field.