Forms
Field
Layout parts for forms: a label, the control, a description and an error, stacked with consistent spacing. Group fields with FieldGroup and FieldSet.
import * as Field from '@statix/ui/field';Playground
We send invoices to this address.
<Field.Field>
<Field.Label for="email">Email</Field.Label>
<Input id="email" type="email" />
<Field.Description>We send invoices to this address.</Field.Description>
</Field.Field>Examples
Settings form
FieldSet with a legend and description, then a FieldGroup of fields. Each field stacks label, control and an optional description 8px apart.
<script lang="ts">
import { Button } from '@statix/ui/button';
import * as Field from '@statix/ui/field';
import { Input } from '@statix/ui/input';
</script>
<form class="w-full max-w-md" onsubmit={(e) => e.preventDefault()}>
<Field.Set>
<Field.Legend>Personal details</Field.Legend>
<Field.Description
>We use these to reach you about your contract and invoices.</Field.Description
>
<Field.Group>
<Field.Field>
<Field.Label for="pd-name">Full name</Field.Label>
<Input id="pd-name" autocomplete="name" value="Anna Berger" />
</Field.Field>
<Field.Field>
<Field.Label for="pd-email">Email</Field.Label>
<Input id="pd-email" type="email" autocomplete="email" value="anna@yoga-berger.de" />
</Field.Field>
<Field.Field>
<Field.Label for="pd-phone">Phone</Field.Label>
<Input
id="pd-phone"
type="tel"
autocomplete="tel"
placeholder="040 123 456 78"
aria-describedby="pd-phone-desc"
/>
<Field.Description id="pd-phone-desc">
Only used if your website goes down and we can't reach you by email.
</Field.Description>
</Field.Field>
<Field.Field orientation="horizontal">
<Button type="submit">Save changes</Button>
<Button variant="ghost" type="reset">Cancel</Button>
</Field.Field>
</Field.Group>
</Field.Set>
</form>With an error
Set data-invalid on the field and aria-invalid on the control. FieldError renders the message with role="alert".
<script lang="ts">
import { Button } from '@statix/ui/button';
import * as Field from '@statix/ui/field';
import { Input } from '@statix/ui/input';
</script>
<form class="w-full max-w-sm" onsubmit={(e) => e.preventDefault()}>
<Field.Group>
<Field.Field>
<Field.Label for="login-email">Email</Field.Label>
<Input id="login-email" type="email" autocomplete="username" value="anna@yoga-berger.de" />
</Field.Field>
<Field.Field data-invalid="true">
<Field.Label for="login-password">Password</Field.Label>
<Input
id="login-password"
type="password"
autocomplete="current-password"
value="yoga2024"
aria-invalid="true"
aria-describedby="login-password-error"
/>
<Field.Error id="login-password-error">
This password doesn't match. Reset it or call us on 040 468 970 790.
</Field.Error>
</Field.Field>
<Button type="submit" class="w-full">Log in</Button>
</Field.Group>
</form>Horizontal
orientation="horizontal" puts a switch or checkbox next to its label. Wrap label and description in FieldContent.
We update WordPress and plugins every night after a backup.
A short email with uptime, backups and updates.
<script lang="ts">
import { Checkbox } from '@statix/ui/checkbox';
import * as Field from '@statix/ui/field';
import { Switch } from '@statix/ui/switch';
</script>
<Field.Group class="w-full max-w-md">
<Field.Field orientation="horizontal">
<Field.Content>
<Field.Label for="h-updates">Automatic updates</Field.Label>
<Field.Description>
We update WordPress and plugins every night after a backup.
</Field.Description>
</Field.Content>
<Switch id="h-updates" checked />
</Field.Field>
<Field.Field orientation="horizontal">
<Checkbox id="h-report" checked />
<Field.Content>
<Field.Label for="h-report">Monthly report</Field.Label>
<Field.Description>A short email with uptime, backups and updates.</Field.Description>
</Field.Content>
</Field.Field>
</Field.Group>Choice cards
Wrap a whole Field in FieldLabel to make a selectable tile. The tile turns primary-soft when its radio or checkbox is checked.
<script lang="ts">
import * as Field from '@statix/ui/field';
import * as RadioGroup from '@statix/ui/radio-group';
let delivery = $state('email');
</script>
<Field.Set class="w-full max-w-md">
<Field.Legend variant="label">Invoice delivery</Field.Legend>
<RadioGroup.Root bind:value={delivery}>
<Field.Label for="cc-email">
<Field.Field orientation="horizontal">
<Field.Content>
<Field.Title>By email</Field.Title>
<Field.Description>PDF to anna@yoga-berger.de. Free.</Field.Description>
</Field.Content>
<RadioGroup.Item value="email" id="cc-email" />
</Field.Field>
</Field.Label>
<Field.Label for="cc-post">
<Field.Field orientation="horizontal">
<Field.Content>
<Field.Title>By post</Field.Title>
<Field.Description
>Printed and sent to your address. 1.50 € per invoice.</Field.Description
>
</Field.Content>
<RadioGroup.Item value="post" id="cc-post" />
</Field.Field>
</Field.Label>
</RadioGroup.Root>
</Field.Set>Responsive rows
orientation="responsive" stacks on narrow screens and puts the label left of the control once the FieldGroup is wider than 28rem.
Visitors to other domains are sent here.
Gets alerts when the website is down.
<script lang="ts">
import * as Field from '@statix/ui/field';
import { Input } from '@statix/ui/input';
</script>
<Field.Group class="w-full max-w-2xl">
<Field.Field orientation="responsive">
<Field.Content>
<Field.Label for="r-domain">Main domain</Field.Label>
<Field.Description>Visitors to other domains are sent here.</Field.Description>
</Field.Content>
<Input id="r-domain" value="yoga-berger.de" class="@md/field-group:max-w-64" />
</Field.Field>
<Field.Separator />
<Field.Field orientation="responsive">
<Field.Content>
<Field.Label for="r-contact">Technical contact</Field.Label>
<Field.Description>Gets alerts when the website is down.</Field.Description>
</Field.Content>
<Input id="r-contact" type="email" value="it@yoga-berger.de" class="@md/field-group:max-w-64" />
</Field.Field>
</Field.Group>Guidelines
Do
- Use one column. People fill forms top to bottom.
- Put help text under the control as FieldDescription, and replace it with FieldError when the value is wrong.
- Group related fields in a FieldSet with a legend, such as "Personal details" or "Invoice address".
Don't
- Don't show errors before people have finished typing.
- Don't colour the label red. The border and the message carry the error.
Accessibility
- Field renders role="group". FieldSet renders a native <fieldset> and FieldLegend its <legend>, so the legend names every control inside.
- FieldLabel is a <label>. Point for at the control id.
- Link FieldDescription or FieldError to the control with aria-describedby. FieldError has role="alert" and is read out when it appears.
- Choice cards keep the radio or checkbox focusable; the tile shows the focus ring.
API reference
Field.Field
renders<div role="group"> and accepts its attributesOne form field. Holds a label, the control and its messages.
| Prop | Type | Default |
|---|---|---|
orientation | 'vertical' | 'horizontal' | 'responsive' Stack, side by side, or side by side once the FieldGroup is wide enough. | 'vertical' |
ref bind | HTMLDivElement | null The rendered element. | – |
class | ClassValue Merged with the default classes; yours win. | – |
| Data attribute | Meaning |
|---|---|
data-slot="field" | Always present. |
data-orientation | The current orientation. |
data-invalid="true" | Set it yourself to mark the field as invalid. |
data-disabled="true" | Set it yourself to fade labels of a disabled field. |
Field.Label
renders<label> and accepts its attributesLabel for the control. Wrap a whole Field in it to make a choice card.
| Prop | Type | Default |
|---|---|---|
for | string id of the control. | – |
ref bind | HTMLLabelElement | null The rendered element. | – |
class | ClassValue Merged with the default classes; yours win. | – |
| Data attribute | Meaning |
|---|---|
data-slot="field-label" | Always present. |
Field.Description
renders<p> and accepts its attributesHelp text under the control, 13.5px muted.
| Prop | Type | Default |
|---|---|---|
ref bind | HTMLElement | null The rendered element. | – |
class | ClassValue Merged with the default classes; yours win. | – |
Field.Error
renders<div role="alert"> and accepts its attributesError message in destructive red. Renders nothing when it has no content.
| Prop | Type | Default |
|---|---|---|
errors | { message?: string }[] Messages to show instead of children. Two or more render as a list. | – |
ref bind | HTMLDivElement | null The rendered element. | – |
class | ClassValue Merged with the default classes; yours win. | – |
| Data attribute | Meaning |
|---|---|
data-slot="field-error" | Present when it renders. |
Field.Content
renders<div> and accepts its attributesStacks a label and description next to a control in horizontal fields.
| Prop | Type | Default |
|---|---|---|
ref bind | HTMLElement | null The rendered element. | – |
class | ClassValue Merged with the default classes; yours win. | – |
Field.Title
renders<div> and accepts its attributesLabel-styled text that is not a <label>, for choice cards.
| Prop | Type | Default |
|---|---|---|
ref bind | HTMLElement | null The rendered element. | – |
class | ClassValue Merged with the default classes; yours win. | – |
Field.Group
renders<div> and accepts its attributesStacks fields 24px apart. Container for the responsive orientation.
| Prop | Type | Default |
|---|---|---|
ref bind | HTMLElement | null The rendered element. | – |
class | ClassValue Merged with the default classes; yours win. | – |
Field.Set
renders<fieldset> and accepts its attributesGroups related fields with a legend.
| Prop | Type | Default |
|---|---|---|
ref bind | HTMLElement | null The rendered element. | – |
class | ClassValue Merged with the default classes; yours win. | – |
Field.Legend
renders<legend> and accepts its attributesCaption of a FieldSet.
| Prop | Type | Default |
|---|---|---|
variant | 'legend' | 'label' legend is 17px subtitle text. label matches a field label. | 'legend' |
class | ClassValue Merged with the default classes; yours win. | – |
Field.Separator
renders<div> and accepts its attributesHairline between fields, with optional text in the middle.
| Prop | Type | Default |
|---|---|---|
ref bind | HTMLElement | null The rendered element. | – |
class | ClassValue Merged with the default classes; yours win. | – |