Number field

Example

<label for="number-field-seats">Seats</label>
<div data-slean="number-field">
	<button type="button" tabindex="-1" aria-label="Decrease" data-slean-part="decrement"></button>
	<input id="number-field-seats" type="number" name="seats" min="1" max="20" value="4"
		data-slean-part="input" />
	<button type="button" tabindex="-1" aria-label="Increase" data-slean-part="increment"></button>
</div>

<script lang="ts">
	// With @svelte-lean/vite the register import is injected for the static data-slean="number-field".
	import '@svelte-lean/styles/number-field.css';

	let seats = $state(4);
</script>

<label for="seats">Seats</label>
<div data-slean="number-field">
	<button type="button" tabindex="-1" aria-label="Decrease" data-slean-part="decrement"></button>
	<input id="seats" type="number" name="seats" min="1" max="20" bind:value={seats}
		data-slean-part="input" />
	<button type="button" tabindex="-1" aria-label="Increase" data-slean-part="increment"></button>
</div>
<p>{seats} seats</p>

Why this implementation exists

<input type="number"> already parses, validates, steps with the arrow keys and submits. What it does not do well is its spin buttons: small, different in every engine, impossible to style and awkward on touch.

The number field replaces them with two ordinary buttons and one shared click listener that calls stepUp() or stepDown(), then dispatches input and change as a user edit would. Because the platform performs the step, step, min, max and the snapping to the step base are the input’s own rules, not a reimplementation.

Usage

Install @svelte-lean/primitives for the behavior and @svelte-lean/styles for the stylesheet. With @svelte-lean/vite the registration is injected for every static data-slean="number-field"; without it, import the register module once.

npm install @svelte-lean/primitives

pnpm add @svelte-lean/primitives

yarn add @svelte-lean/primitives

bun add @svelte-lean/primitives

import '@svelte-lean/primitives/number-field/register';

import '@svelte-lean/styles/number-field.css';

Put the input and the two buttons in a root; label the input with <label for>. Give the buttons tabindex="-1" and an aria-label.

Bind the input with bind:value; a click on a button reaches the binding through the dispatched input event.

Anatomy

Runtime profile

The number field registers one click handler with the shared router. A thousand fields keep one listener (tests/number-field.test.ts).

Accessibility contract

• The input is a native spin button, named by its label and announced with its value.
• The buttons are out of the tab order, as in the WAI-ARIA spinbutton pattern: ArrowUp and ArrowDown do what they do.
• At min or max the platform refuses the step and nothing is dispatched.
• The focus ring is drawn around the whole field while the input has keyboard focus.

Keyboard

Platform features

Without JavaScript

The input works with its native spin buttons and keys. The stylesheet hides the two buttons under @media (scripting: none), so the page offers only what works.

Server rendering

Render the input with its value. Nothing is written by the behavior before a click.

Before hydration

Before the behavior loads, the buttons do nothing; typing and the arrow keys work.

Styling

number-field.css draws one box around the buttons and the input, a minus and a plus with pseudo-elements, the focus ring on the box through :has(), the invalid border from :user-invalid, and hides the native spin buttons only while scripting is enabled. The tokens it reads:

State selectors the stylesheet targets, all from the platform or ARIA: ::-webkit-inner-spin-button, :disabled, :focus-visible, :hover, :user-invalid, [aria-invalid="true"].

Variant attributes: data-status (warning, error).

Compatibility notes

stepUp() and stepDown() are widely available. step="any" cannot be stepped; the buttons then do nothing. Press-and-hold repeat and number formatting are not part of the primitive.

Testing

• packages/primitives/tests/number-field.test.ts Vitest: stepping within bounds, events, disabled and read-only, step="any", 1000 roots
• apps/playground/tests/primitives/widgets.spec.ts Playwright: tooltip, toast, tree, range slider and number field in Chrome, with axe
• packages/styles/tests static checks of the stylesheet (layers, tokens, specificity, dark parity)

Source

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