Skip to content
Statix Design System

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.

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

Personal details

We use these to reach you about your contract and invoices.

Only used if your website goes down and we can't reach you by email.

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

Invoice delivery
<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 attributes

One form field. Holds a label, the control and its messages.

PropTypeDefault
orientation 'vertical' | 'horizontal' | 'responsive'

Stack, side by side, or side by side once the FieldGroup is wide enough.

'vertical'
ref bindHTMLDivElement | null

The rendered element.

–
class ClassValue

Merged with the default classes; yours win.

–
Data attributeMeaning
data-slot="field"Always present.
data-orientationThe 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 attributes

Label for the control. Wrap a whole Field in it to make a choice card.

PropTypeDefault
for string

id of the control.

–
ref bindHTMLLabelElement | null

The rendered element.

–
class ClassValue

Merged with the default classes; yours win.

–
Data attributeMeaning
data-slot="field-label"Always present.

Field.Description

renders <p> and accepts its attributes

Help text under the control, 13.5px muted.

PropTypeDefault
ref bindHTMLElement | null

The rendered element.

–
class ClassValue

Merged with the default classes; yours win.

–

Field.Error

renders <div role="alert"> and accepts its attributes

Error message in destructive red. Renders nothing when it has no content.

PropTypeDefault
errors { message?: string }[]

Messages to show instead of children. Two or more render as a list.

–
ref bindHTMLDivElement | null

The rendered element.

–
class ClassValue

Merged with the default classes; yours win.

–
Data attributeMeaning
data-slot="field-error"Present when it renders.

Field.Content

renders <div> and accepts its attributes

Stacks a label and description next to a control in horizontal fields.

PropTypeDefault
ref bindHTMLElement | null

The rendered element.

–
class ClassValue

Merged with the default classes; yours win.

–

Field.Title

renders <div> and accepts its attributes

Label-styled text that is not a <label>, for choice cards.

PropTypeDefault
ref bindHTMLElement | null

The rendered element.

–
class ClassValue

Merged with the default classes; yours win.

–

Field.Group

renders <div> and accepts its attributes

Stacks fields 24px apart. Container for the responsive orientation.

PropTypeDefault
ref bindHTMLElement | null

The rendered element.

–
class ClassValue

Merged with the default classes; yours win.

–

Field.Set

renders <fieldset> and accepts its attributes

Groups related fields with a legend.

PropTypeDefault
ref bindHTMLElement | null

The rendered element.

–
class ClassValue

Merged with the default classes; yours win.

–

Field.Legend

renders <legend> and accepts its attributes

Caption of a FieldSet.

PropTypeDefault
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 attributes

Hairline between fields, with optional text in the middle.

PropTypeDefault
ref bindHTMLElement | null

The rendered element.

–
class ClassValue

Merged with the default classes; yours win.

–