Primitives Forms
Field
A label, a control, a hint and an error message laid out together and related through the platform’s label and aria-describedby.
Markdown version of this page, for assistants (Markdown for AI)
On this page
The receipt is sent to this address.
Code
<script lang="ts">
import '@svelte-lean/styles/field.css';
import '@svelte-lean/styles/input.css';
</script>
<div data-slean="field">
<label for="field-email" data-slean-part="label">Email</label>
<input
id="field-email"
type="email"
name="email"
autocomplete="email"
aria-describedby="field-email-description"
data-slean="input"
/>
<p id="field-email-description" data-slean-part="description">
The receipt is sent to this address.
</p>
</div>Examples
Validation
Letters, digits and hyphens.
This username is taken.
Code
<script lang="ts">
import '@svelte-lean/styles/field.css';
import '@svelte-lean/styles/input.css';
const taken = ['ada', 'grace', 'alan'];
let username = $state('ada');
const error = $derived(
!/^[a-z0-9-]*$/i.test(username)
? 'Use letters, digits and hyphens only.'
: taken.includes(username.toLowerCase())
? 'This username is taken.'
: ''
);
</script>
<!-- The error part and aria-invalid exist only while there is an error. -->
<div data-slean="field">
<label for="field-username" data-slean-part="label">Username</label>
<input
id="field-username"
name="username"
autocomplete="username"
bind:value={username}
aria-describedby={error
? 'field-username-description field-username-error'
: 'field-username-description'}
aria-invalid={error ? 'true' : undefined}
data-slean="input"
/>
<p id="field-username-description" data-slean-part="description">
Letters, digits and hyphens.
</p>
{#if error}
<p id="field-username-error" data-slean-part="error">{error}</p>
{/if}
</div>Validation messages from the browser
Code
<script lang="ts">
// data-slean-validate makes @svelte-lean/vite add the field/validation option module.
import '@svelte-lean/styles/button.css';
import '@svelte-lean/styles/field.css';
import '@svelte-lean/styles/input.css';
</script>
<!-- The browser decides and words the message; the field shows it under the control. -->
<form class="signup" onsubmit={(event) => event.preventDefault()}>
<div data-slean="field" data-slean-validate>
<label for="field-signup-email" data-slean-part="label">Email</label>
<input
id="field-signup-email"
type="email"
name="email"
required
aria-describedby="field-signup-email-description"
data-slean="input"
/>
<p id="field-signup-email-description" data-slean-part="description">
The receipt is sent here.
</p>
</div>
<div data-slean="field" data-slean-validate>
<label for="field-signup-handle" data-slean-part="label">Handle</label>
<input
id="field-signup-handle"
name="handle"
required
minlength="3"
pattern="[a-z0-9-]+"
data-slean="input"
/>
</div>
<button type="submit" data-slean="button">Create account</button>
</form>
<style>
.signup {
display: grid;
justify-items: start;
gap: 1rem;
max-inline-size: 22rem;
}
.signup > [data-slean='field'] {
justify-self: stretch;
}
</style>Horizontal
Shown on your posts.
Code
<script lang="ts">
import '@svelte-lean/styles/field.css';
import '@svelte-lean/styles/input.css';
</script>
<div class="stack">
<div data-slean="field" data-slean-orientation="horizontal">
<label for="field-name" data-slean-part="label">Display name</label>
<input
id="field-name"
name="name"
autocomplete="nickname"
aria-describedby="field-name-description"
data-slean="input"
/>
<p id="field-name-description" data-slean-part="description">Shown on your posts.</p>
</div>
<div data-slean="field" data-slean-orientation="horizontal">
<label for="field-website" data-slean-part="label">Website</label>
<input id="field-website" type="url" name="website" autocomplete="url" data-slean="input" />
</div>
</div>
<style>
.stack {
display: grid;
gap: 1.25rem;
max-inline-size: 32rem;
}
</style>Group control
Used for distances and weights.
Code
<script lang="ts">
import '@svelte-lean/styles/field.css';
import '@svelte-lean/styles/radio-group.css';
</script>
<!-- A fieldset is named by its legend: no label part, and aria-describedby on the fieldset. -->
<div data-slean="field">
<fieldset data-slean="radio-group" data-variant="segmented" aria-describedby="field-units-description">
<legend>Units</legend>
<label><input type="radio" name="field-units" value="metric" checked /> Metric</label>
<label><input type="radio" name="field-units" value="imperial" /> Imperial</label>
</fieldset>
<p id="field-units-description" data-slean-part="description">
Used for distances and weights.
</p>
</div>Character count
126 characters left.
Code
<script lang="ts">
import '@svelte-lean/styles/field.css';
import '@svelte-lean/styles/input.css';
const max = 160;
let bio = $state('Maps tides for the harbour office.');
</script>
<div data-slean="field">
<label for="field-bio" data-slean-part="label">Bio</label>
<textarea
id="field-bio"
name="bio"
maxlength={max}
bind:value={bio}
aria-describedby="field-bio-description"
data-slean="input"
></textarea>
<p id="field-bio-description" data-slean-part="description">
{max - bio.length} characters left.
</p>
</div>Disabled and read-only
Set when it was created.
Code
<script lang="ts">
import '@svelte-lean/styles/field.css';
import '@svelte-lean/styles/input.css';
</script>
<!-- A disabled control mutes its label; a read-only one stays focusable and is submitted. -->
<div class="stack">
<div data-slean="field">
<label for="field-plan" data-slean-part="label">Plan</label>
<input id="field-plan" name="plan" value="Team" disabled data-slean="input" />
</div>
<div data-slean="field">
<label for="field-workspace" data-slean-part="label">Workspace ID</label>
<input
id="field-workspace"
name="workspace"
value="ws-4512"
readonly
aria-describedby="field-workspace-description"
data-slean="input"
/>
<p id="field-workspace-description" data-slean-part="description">Set when it was created.</p>
</div>
</div>
<style>
.stack {
display: grid;
gap: 1.25rem;
max-inline-size: 32rem;
}
</style>Helper or plain markup
Two ways to write the same markup: with fieldParts() or by hand. Both render the same
HTML, which a test of this site compares; use either.
<script lang="ts">
import { fieldParts } from '@svelte-lean/primitives/field';
const f = fieldParts('username', {
description: true,
error: true
});
</script>
<div data-slean="field">
<label {...f.label}>Username</label>
<input {...f.control} name="username" data-slean="input" />
<p {...f.description}>Letters, digits and hyphens.</p>
<p {...f.error}>This username is taken.</p>
</div><div data-slean="field">
<label for="username" data-slean-part="label">Username</label>
<input
id="username"
aria-describedby="username-description username-error"
aria-invalid="true"
name="username"
data-slean="input"
/>
<p id="username-description" data-slean-part="description">
Letters, digits and hyphens.
</p>
<p id="username-error" data-slean-part="error">
This username is taken.
</p>
</div>What the helper does
- One id in, every reference out:
fieldParts('username', { description: true, error: true })writesusername-descriptionandusername-errorand lists both, in that order, in the control’saria-describedby. - Strings only: no handler, no state, no instance. The server and the browser render the same attributes, so hydration has nothing to patch.
error: trueaddsaria-invalid="true"with the reference, so the state and the message come and go together;<id>-erroris also the id the validation module uses.
Points to watch
- The id is the control’s own id, not a root id: spread
f.controlon the<input>or<select>,f.labelon the<label>. - It registers nothing and imports no stylesheet: the root's
data-slean="field"stay in your markup, where@svelte-lean/vitefinds it. - With
data-slean-validate, leaveerrorout: the validation module writesaria-invalidand the error part when the browser reports an error. - Ids must be unique on the page. Hand-written markup works the same; the ids and the references between them are then yours to keep in step.
Usage
Plain markup with a stylesheet: install @svelte-lean/styles. No JavaScript runs.
npm install @svelte-lean/stylespnpm add @svelte-lean/stylesyarn add @svelte-lean/stylesbun add @svelte-lean/stylesimport '@svelte-lean/styles/input.css';
import '@svelte-lean/styles/field.css';Wrap the label, the control and the messages in <div data-slean="field"> and mark them with data-slean-part: label, description, error. Give the description and the error ids, and list them in the control’s aria-describedby.
Render the error part and aria-invalid="true" only while there is an error; the control’s own stylesheet colors it.
For the browser’s own messages (required, type, pattern, min, minlength, setCustomValidity()) under the field instead of its bubble, add data-slean-validate to the field: the option module writes the message into the error part (creating it when missing), sets aria-invalid, focuses the first invalid control on submit and clears the message when the value is valid. The module ships only on pages that use the attribute.
Anatomy
| Part | Element | data-slean-part | Required | Notes |
|---|---|---|---|---|
| root | <div data-slean="field"> | – | yes | Options: data-slean-orientation="horizontal" puts the label beside the control; data-slean-validate shows the browser’s validation messages (option module). |
| label | <label for="…"> | label | yes | Names the control. Omitted when the control is a fieldset with its own legend. |
| control | <input>, <select>, <textarea>, a fieldset, … | – | yes | Its own primitive and stylesheet; aria-describedby lists the description and error ids. |
| description | <p id="…"> | description | no | A hint, read as part of the control’s description. |
| error | <p id="…"> | error | no | Rendered by the application with aria-invalid="true" on the control, and removed with it; with data-slean-validate, the browser’s message written by the module (the part is created when missing). |
Keyboard
| Key | When | Result |
|---|---|---|
| Tab | on the page | Reaches the control; the label, description and error are not focusable (native) |
Styling
field.css stacks the parts or places them in two columns, gives the description and the error one helper-text look (the error in the error color, an empty error taking no space), turns the label to the error color while the control is invalid, and mutes the label and description of a disabled control through :has(). The control’s colors come from its own stylesheet. The tokens it reads:
| Token | Default (light) | Applies to |
|---|---|---|
--slean-space-2 | calc(var(--slean-spacing) * 2) | gap |
--slean-fg | var(--slean-neutral-12) | color |
--slean-text-sm | 0.875rem | font-size |
--slean-font-weight-medium | 500 | font-weight |
--slean-fg-muted | var(--slean-neutral-11) | color |
--slean-space-1 | calc(var(--slean-spacing) * 1) | margin-block-start |
--slean-error-main | oklch(52% 0.19 25) | color |
--slean-space-4 | calc(var(--slean-spacing) * 4) | gap |
State selectors the stylesheet targets, all from the platform or ARIA: :disabled, :empty, :user-invalid, [aria-invalid="true"], [type="color"], [type="date"], [type="datetime-local"], [type="month"], [type="number"], [type="time"], [type="week"].
Variant attributes: data-slean-orientation (horizontal).
Controlled integration
With a SvelteKit form action, the server returns the error with the submitted value (fail(400, { username, errors })), and the page renders the error part and aria-invalid from them. The same page works with JavaScript disabled.
<script lang="ts">
// +page.svelte: the error part and aria-invalid exist only when there is an error.
let { form } = $props();
const error = $derived(form?.errors?.username);
</script>
<form method="POST">
<div data-slean="field">
<label for="username" data-slean-part="label">Username</label>
<input id="username" name="username" value={form?.username ?? ''}
aria-describedby={error ? 'username-error' : undefined}
aria-invalid={error ? 'true' : undefined} data-slean="input" />
{#if error}
<p id="username-error" data-slean-part="error">{error}</p>
{/if}
</div>
<button data-slean="button">Save</button>
</form>Under the hood
Runtime and size
- Tier
- 0 · Native
- Behavior JS
- 0 B brotli · 0 B gzip ·
fixtures/· methodresults.json (native-only) - Platform features
<label for>,aria-describedby,aria-invalid,:has()- Shared listeners
- none
- Per-instance listeners
- none
- Lazy state
- none
- Native base
<label for>, a control, aria-describedby; constraint validation
Tier 0: the field has no behavior module, the Vite plugin maps field to no module, and the native-only fixture proves the path ships no Svelte Lean JavaScript. With data-slean-validate the plugin adds the field/validation option module (Tier 1: shared invalid, focusout, input, change and reset listeners, no state); the fields-owned fixture asserts it ships only there.
Why this implementation
A label, a hint and an error message are three elements and two attributes. <label for> gives the control its name, aria-describedby gives it a description made of the listed elements in the listed order, and aria-invalid exposes the error state. A field component that generates the ids and wires them spends script and state on what is markup.
What the platform does not decide is where an error comes from. The contract’s answer is the application: the server, or the application’s own validation, renders the message and aria-invalid together and removes both when the value is fixed. The stylesheet never reveals a hidden message on :user-invalid, because a hidden element listed in aria-describedby is still read as part of the description, and one that is not listed is never read.
The browser owns
- the accessible name from <label for>, and focus on a label click
- the accessible description from aria-describedby, in the listed order
- the error state from aria-invalid and from constraint validation
- the platform’s own message on submit for a constraint the value breaks, and its text (validationMessage, setCustomValidity())
Svelte Lean owns
- field.css: the stacked and the horizontal layout, label, description and error type, the muted label of a disabled control
- the contract: which ids go where, and why an error is rendered rather than revealed
- with data-slean-validate (an option module): the browser’s message in the error part, aria-invalid, focus on the first invalid control, cleared when valid
Accessibility
<label for>names the control; a click on the label focuses it.aria-describedbylists the description and then the error; screen readers read them after the name and the role.aria-invalid="true"with a visible message marks an error the application found. The browser reportsrequired,typeandpatternfailures itself on submit.- A group control is a fieldset named by its legend, and
aria-describedbygoes on the fieldset. - The error is text, not a color alone, so it survives forced colors and color blindness.
Platform features
| Feature | Baseline | Outside the target |
|---|---|---|
<label for>, aria-describedby, aria-invalid | Widely available | Not applicable |
:has() | Baseline 2023 (Chrome 105, Safari 15.4, Firefox 121) | The label of a disabled control keeps its color |
Constraint validation, validationMessage, the invalid event | Widely available | Not applicable |
Without JavaScript
Fully functional: a form that posts and renders the returned errors works without JavaScript, and the browser blocks a submit that breaks a constraint.
Server rendering and hydration
Everything is markup. A server-side validation answer renders the same field with the error part and aria-invalid.
Nothing is attached. An error rendered on the server is in the document before hydration and stays until the application removes it.
Compatibility
Labels, aria-describedby and aria-invalid are widely available. :has() (Baseline 2023) mutes the label of a disabled control; where it is missing the label keeps its color.
Tests and source
packages/primitives/tests/field-validation.test.tsVitest: the validation option module, messages, aria-invalid, focus, reset, helpersapps/playground/tests/primitives/forms.spec.tsPlaywright: keyboard, form values, :user-invalid, names and descriptions, axeapps/playground/tests/primitives/fields.spec.tsPlaywright, with page JavaScript enabled and disabled, and axepackages/styles/testsstatic checks of the stylesheet (layers, tokens, specificity, dark parity)fixtures/native-onlyconsumer build asserting that no behavior runtime ships (invariant A)
packages/primitives/src/field/contract.mdthe contract in prose: semantics, keyboard, focus, ARIA, SSR, JS-disabled behaviorpackages/primitives/src/field/contract.tstyped constants: name, tier, base, parts, options, eventspackages/styles/css/field.cssthe optional stylesheet