Checkbox

Example

<label>
	<input type="checkbox" name="terms" data-slean="checkbox" />
	I agree to the terms
</label>
<label>
	<input type="checkbox" name="updates" data-slean="checkbox" checked />
	Product updates by email
</label>
<label>
	<input type="checkbox" name="locked" data-slean="checkbox" disabled />
	Locked by an administrator
</label>

<script lang="ts">
	// Nothing to import: the browser owns the checkbox. The stylesheet is optional.
	import '@svelte-lean/styles/checkbox.css';
</script>

<label>
	<input type="checkbox" name="terms" data-slean="checkbox" />
	I agree to the terms
</label>
<label>
	<input type="checkbox" name="updates" data-slean="checkbox" checked />
	Product updates by email
</label>
<label>
	<input type="checkbox" name="locked" data-slean="checkbox" disabled />
	Locked by an administrator
</label>

Why this implementation exists

The native checkbox has the checked, indeterminate and disabled states, Space to toggle, the label association, form participation, constraint validation and the accessible role and name. A <div role="checkbox"> re-creates part of that in JavaScript and loses the form. With appearance: none the native control can be drawn any way, so the reason to replace it is gone. Svelte Lean therefore ships a stylesheet and a contract and nothing else; the state is read from the input or from FormData, never from a mirror.

Usage

The markup needs no package. Install @svelte-lean/styles for the stylesheet; @svelte-lean/primitives adds the typed contract and nothing at runtime.

npm install @svelte-lean/styles

pnpm add @svelte-lean/styles

yarn add @svelte-lean/styles

bun add @svelte-lean/styles

import '@svelte-lean/styles/tokens.css';
import '@svelte-lean/styles/base.css';
import '@svelte-lean/styles/checkbox.css';

Use a checkbox for a value that is submitted with a form or applied on save. Use a Switch when toggling has an immediate effect. Related checkboxes go in a <fieldset> with a <legend>; a single choice among several is a Radio group.

Anatomy

Runtime profile

The runtime block reads the tier and the events from the contract and the bytes from the native-only consumer fixture: a production Vite build with the Vite plugin whose module graph contains no @svelte-lean/core or @svelte-lean/primitives module. The fixture's markup is button, dialog and popover; the checkbox path is proven the same way by construction: packages/primitives/src/checkbox has no behavior, validate or register module, the plugin maps checkbox to no module, and the playground's bundle spec asserts that the native page, which includes this markup, loads no behavior runtime. Nothing is attached at hydration.

Accessibility contract

• An <input type="checkbox"> with a label: a wrapping <label>, or for and id.
• State is :checked, :indeterminate, :disabled and, with required, :user-invalid. No aria-checked; the native state is exposed.
• disabled: not focusable and not submitted. Related checkboxes are grouped by a <fieldset> with a <legend>.
• The indeterminate state is the indeterminate property, set from script; it is not an attribute and cannot be server-rendered.

Keyboard

Platform features

Without JavaScript

Fully functional. The playground's native page runs the click, label and Space assertions with page JavaScript disabled. Only the indeterminate state, being a property, needs a script.

Server rendering

The checked attribute renders the initial state and forms work before hydration. Ids are authored when for is used.

Before hydration

The delayed-hydration test clicks a label and asserts the checkbox is checked while every script response is held back. Hydration attaches nothing to an input the package does not bind; an application that uses bind:checked follows Svelte's own hydration rules for bound inputs.

Styling

checkbox.css sets appearance: none and draws the mark with borders on ::before, a bar for :indeterminate, a danger border for :user-invalid, and on coarse pointers an invisible hit area on ::after. Under forced colors it opts out of the automatic adjustment and uses the system colors. The tokens it reads and the states it targets:

State selectors the stylesheet targets, all from the platform or ARIA: :checked, :disabled, :hover, :indeterminate, :user-invalid, [aria-invalid="true"].

Controlled integration

The input is the state. Svelte reads and writes it with bind:checked and bind:group, and bind:indeterminate covers the mixed state of a "select all" control. The package mirrors nothing and dispatches no slean:* event for a checkbox; a Svelte adapter is not built and is not needed for this primitive.

<script lang="ts">
	// The input is the state. bind:checked reads and writes it; FormData reads it on submit.
	let agreed = $state(false);
	let channels = $state<string[]>(['email']);
</script>

<label>
	<input type="checkbox" name="terms" data-slean="checkbox" bind:checked={agreed} required />
	I agree to the terms
</label>

<fieldset>
	<legend>Notifications</legend>
	<label><input type="checkbox" data-slean="checkbox" bind:group={channels} value="email" /> Email</label>
	<label><input type="checkbox" data-slean="checkbox" bind:group={channels} value="sms" /> SMS</label>
</fieldset>

<script lang="ts">
	let rows = $state([true, false, true]);
	const checked = $derived(rows.filter(Boolean).length);
	// indeterminate is a property, not an attribute: it is set from script and cannot be
	// server-rendered. Svelte binds it like checked.
	let mixed = $derived(checked > 0 && checked < rows.length);
	let all = $derived(checked === rows.length);
</script>

<label>
	<input
		type="checkbox"
		data-slean="checkbox"
		bind:indeterminate={mixed}
		checked={all}
		onchange={(event) => (rows = rows.map(() => event.currentTarget.checked))}
	/>
	Select all
</label>

Compatibility notes

appearance: none, :checked and :indeterminate are Baseline widely available; :user-invalid is Baseline 2023 and only affects the invalid border. There is no fallback case for the control itself. The policy is on Browser support.

Testing

• apps/playground/tests/primitives/native.spec.ts Playwright, with page JavaScript enabled and disabled
• apps/playground/tests/primitives/a11y.spec.ts axe on every playground page and on open dialog, popover and menu states
• packages/styles/tests static checks of the stylesheet (layers, tokens, specificity, dark parity)
• fixtures/native-only consumer build asserting that no behavior runtime ships (invariant A)

Source

• packages/primitives/src/checkbox/contract.md the contract in prose: semantics, keyboard, focus, ARIA, SSR, JS-disabled behavior
• packages/primitives/src/checkbox/contract.ts typed constants: name, tier, base, parts, options, events
• packages/styles/css/checkbox.css the optional stylesheet