sveltelean Primitives
Version v0.18.0
Email with a hint

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>
Click the label to focus the input; the hint is read as its description.

Examples

Validation

Username

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>
Type a free username to remove the error. The accessible description is the hint followed by the error.

Validation messages from the browser

Sign up
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>
Submit empty, or type a short handle and leave it: the browser's own message shows under the field, the first invalid field takes focus, and a valid value clears it.

Horizontal

Label beside the control

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>
The label column is up to 10rem wide and aligned with the first line of the control.

Group control

Units
Units

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

Bio

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>
The application writes the count into the description; maxlength stops the typing.

Disabled and read-only

Plan and workspace

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.

With fieldParts()
<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>
Plain markup
<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 }) writes username-description and username-error and lists both, in that order, in the control’s aria-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: true adds aria-invalid="true" with the reference, so the state and the message come and go together; <id>-error is also the id the validation module uses.

Points to watch

  • The id is the control’s own id, not a root id: spread f.control on the <input> or <select>, f.label on the <label>.
  • It registers nothing and imports no stylesheet: the root's data-slean="field" stay in your markup, where @svelte-lean/vite finds it.
  • With data-slean-validate, leave error out: the validation module writes aria-invalid and 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/styles
stylesheets
import '@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

PartElementdata-slean-partRequiredNotes
root<div data-slean="field">–yesOptions: data-slean-orientation="horizontal" puts the label beside the control; data-slean-validate shows the browser’s validation messages (option module).
label<label for="…">labelyesNames the control. Omitted when the control is a fieldset with its own legend.
control<input>, <select>, <textarea>, a fieldset, …–yesIts own primitive and stylesheet; aria-describedby lists the description and error ids.
description<p id="…">descriptionnoA hint, read as part of the control’s description.
error<p id="…">errornoRendered 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

KeyWhenResult
Tabon the pageReaches 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:

TokenDefault (light)Applies to
--slean-space-2calc(var(--slean-spacing) * 2)gap
--slean-fgvar(--slean-neutral-12)color
--slean-text-sm0.875remfont-size
--slean-font-weight-medium500font-weight
--slean-fg-mutedvar(--slean-neutral-11)color
--slean-space-1calc(var(--slean-spacing) * 1)margin-block-start
--slean-error-mainoklch(52% 0.19 25)color
--slean-space-4calc(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.

+page.svelte
<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/results.json (native-only) · method
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-describedby lists 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 reports required, type and pattern failures itself on submit.
  • A group control is a fieldset named by its legend, and aria-describedby goes on the fieldset.
  • The error is text, not a color alone, so it survives forced colors and color blindness.
Platform features
FeatureBaselineOutside the target
<label for>, aria-describedby, aria-invalidWidely availableNot 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 eventWidely availableNot 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