Date picker

Example

<label for="due-text">Due date</label>
<div id="due" data-slean="date-picker" data-slean-format="MM/DD/YYYY">
	<input id="due-date" type="date" name="due" value="2026-09-28" data-slean-part="native" />
	<input
		id="due-text"
		type="text"
		role="combobox"
		aria-haspopup="dialog"
		aria-expanded="false"
		aria-controls="due-popup"
		autocomplete="off"
		placeholder="Select date"
		value="09/28/2026"
		data-slean-part="input"
	/>
	<button type="button" tabindex="-1" aria-label="Clear" data-slean-part="clear"></button>
	<span data-slean-part="icon" aria-hidden="true"></span>
	<div id="due-popup" popover="manual" role="dialog" aria-label="Choose a date" data-slean-part="popup">
		<div data-slean="calendar" data-slean-month="2026-09" data-slean-value="2026-09-28"
			data-slean-input="due-date">
			<!-- the header and the grid, rendered once with calendarMonth() -->
		</div>
		<div data-slean-part="footer">
			<button type="button" data-slean-part="today">Today</button>
		</div>
	</div>
</div>

<script lang="ts">
	// With @svelte-lean/vite the register imports are injected for the static
	// data-slean="date-picker" and data-slean="calendar" markers.
	import '@svelte-lean/styles/control.css';
	import '@svelte-lean/styles/date-field.css';
	import '@svelte-lean/styles/calendar.css';
	import '@svelte-lean/styles/date-picker.css';
	import { formatDisplay } from '@svelte-lean/primitives/date-picker';
	import Month from './Month.svelte'; // the calendar header and grid, rendered once

	const FORMAT = 'MM/DD/YYYY';
	// The native input holds the ISO value; bind:value follows the input and change events.
	let due = $state('2026-09-28');
</script>

<label for="due-text">Due date</label>
<div id="due" data-slean="date-picker" data-slean-format={FORMAT}>
	<input id="due-date" type="date" name="due" data-slean-part="native" bind:value={due} />
	<input
		id="due-text"
		type="text"
		role="combobox"
		aria-haspopup="dialog"
		aria-expanded="false"
		aria-controls="due-popup"
		autocomplete="off"
		placeholder="Select date"
		value={formatDisplay(due, FORMAT)}
		data-slean-part="input"
	/>
	<button type="button" tabindex="-1" aria-label="Clear" data-slean-part="clear"></button>
	<span data-slean-part="icon" aria-hidden="true"></span>
	<div id="due-popup" popover="manual" role="dialog" aria-label="Choose a date" data-slean-part="popup">
		<div data-slean="calendar" data-slean-month="2026-09" data-slean-value="2026-09-28"
			data-slean-input="due-date">
			<Month id="due-cal" month="2026-09" options={{ value: '2026-09-28' }} />
		</div>
		<div data-slean-part="footer">
			<button type="button" data-slean-part="today">Today</button>
		</div>
	</div>
</div>

Why this implementation exists

The native <input type="date"> has the ISO value, min, max, validation and form submission, and it is the right field without JavaScript. Its interface is not the one an application ships: a dd/mm/yyyy mask with no placeholder, a picker glyph that differs in every browser, a platform popup that cannot be styled and no range. ADR 0007 keeps the native input as the value and draws the field over it.

The owned field is the control shell every form control shares (control.css): a text input that shows the date in a display format and accepts typing, the clear button and the calendar icon inside the border, the whole field as the click target. The popup holds a Calendar in single or range mode and an optional footer with Today and preset ranges; the calendar writes the native inputs through data-slean-input, and the date picker writes the text back.

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="date-picker"; 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/date-picker/register';

import '@svelte-lean/styles/control.css';
import '@svelte-lean/styles/date-field.css';
import '@svelte-lean/styles/calendar.css';
import '@svelte-lean/styles/date-picker.css';

Put the native date input (data-slean-part="native", two for a range), one text input per native input (role="combobox", aria-haspopup="dialog", a placeholder and a name), the clear button, the icon and a popover="manual" popup inside data-slean="date-picker". The calendar in the popup names the native inputs with data-slean-input, in order.

Render the text input’s value with formatDisplay(value, format) from @svelte-lean/primitives/date-picker, and the calendar once, with untrack in Svelte: after hydration the calendar behavior owns its cells. Bind the native input with bind:value; the behavior dispatches input and change on it.

The Date field (data-slean="date-field") remains the Tier 0 native input for a table cell or a form without JavaScript.

Anatomy

Runtime profile

Tier 2: a lazy scoped controller. Seven shared listeners (click, keydown, input, change, pointerdown, focusout and toggle in the capture phase) serve every date picker on the page; the calendar inside registers its own click, keydown, pointerover and pointerout. A root gets a WeakMap entry on its first interaction and, while its popup is open, one document pointerdown listener that closes it on a press outside. The bytes in the runtime block include the calendar functions the date picker calls.

Accessibility contract

• Each text input is a role="combobox" with aria-haspopup="dialog", aria-expanded (written) and aria-controls naming the popup; it has a label (or aria-label for the two inputs of a range) and keeps DOM focus while the pointer chooses.
• The popup is a role="dialog" with a name. ArrowDown moves focus to the chosen day (else today); Escape closes and returns focus to the text input; choosing closes and returns focus there.
• Typed text that parses and respects min and max updates the value at once; text that does not parse is replaced by the last valid value when it is committed, so the field never shows a date the form does not hold.
• The clear button and the icon are out of the tab order (tabindex="-1", aria-hidden on the icon); the calendar’s own grid semantics apply inside the popup.

Keyboard

Platform features

Without JavaScript

@media (scripting: none) in date-picker.css hides the text inputs, the icon, the clear button and the popup and shows the native date inputs, with the platform’s picker, typing, validation and form submission. With scripting the rule is reversed, so the page never shows a control that cannot work.

/* date-picker.css: with scripting the native inputs give way to the owned field; without it
 * the native date inputs are the field and the owned parts are not shown. */
@media (scripting: enabled) {
	:where([data-slean='date-picker'] > [data-slean-part='native']) {
		display: none;
	}
}

@media (scripting: none) {
	:where([data-slean='date-picker'] > :is([data-slean-part='input'], [data-slean-part='separator'],
			[data-slean-part='clear'], [data-slean-part='icon'], [data-slean-part='popup'])) {
		display: none;
	}
}

Server rendering

Render the native input’s value, the text input’s value with formatDisplay(), aria-expanded as false, a closed popup and the calendar with calendarMonth() from the same value. formatDisplay() and dateFormat() are pure and run on the server.

Before hydration

Before the behaviors load, the text input can be typed into but nothing opens and the text is not read back; the native value is the server’s. The registration attaches no per-root state, so the first interaction after hydration creates the controller.

Styling

control.css draws the field: border, hover, focus halo, sizes (data-size), status (data-status), the clear button and the icon masks, and the popup surface. date-picker.css adds the separator arrow, the bar under the focused end of a range, the footer, the Today and preset buttons, and the scripting swap; calendar.css draws the header and the grid. The tokens of control.css and date-picker.css:

State selectors the stylesheet targets, all from the platform or ARIA: ::placeholder, :dir(rtl), :disabled, :empty, :focus, :focus-visible, :focus-within, :hover, :placeholder-shown, :popover-open, :user-invalid, [aria-disabled="true"], [aria-expanded="true"], [aria-invalid="true"], [hidden], [popover], [role="listbox"], [role="option"].

Variant attributes: data-status (error, warning); data-size (sm, lg); data-slean-active; data-slean-selected.

Compatibility notes

Popover is Baseline 2024; CSS anchor positioning (Chrome 125, Safari 26) places the popup under the field, and without it the popover popup is centered in the top layer. @media (scripting) is Baseline 2023. The native date input is Baseline 2021; where it is missing it degrades to a text input, so validate the ISO value on the server.

Examples

Range picker

Two native inputs hold the start and the end; two text inputs show them with an arrow between them. The calendar is in range mode with two months side by side: the first choice opens the range, the days under the pointer preview it, and the second choice writes both inputs and closes the popup. Tab moves from the start to the end while the popup stays open. The presets in the footer set a range in one press.

<script lang="ts">
	import { onMount } from 'svelte';
	import { addDays, addMonths, today } from '@svelte-lean/primitives/calendar';
	import { formatDisplay } from '@svelte-lean/primitives/date-picker';
	import Month from './Month.svelte';

	const FORMAT = 'MM/DD/YYYY';
	let start = $state('2026-09-10');
	let end = $state('2026-09-18');

	// Presets are relative to the reader's today, so a prerendered page computes them again in
	// the browser; each preset is data-slean-value="start/end".
	let now = $state('2026-09-28');
	onMount(() => (now = today()));
	const month = $derived(now.slice(0, 7));
	const presets = $derived([
		['Last 7 days', `${addDays(now, -6)}/${now}`],
		['Last 30 days', `${addDays(now, -29)}/${now}`],
		['This month', `${month}-01/${addDays(`${addMonths(month, 1)}-01`, -1)}`]
	]);
</script>

<span id="stay-label">Stay</span>
<div id="stay" data-slean="date-picker" data-slean-format={FORMAT}>
	<input id="stay-start" type="date" name="from" data-slean-part="native" bind:value={start} />
	<input id="stay-end" type="date" name="to" data-slean-part="native" bind:value={end} />
	<input type="text" role="combobox" aria-haspopup="dialog" aria-expanded="false"
		aria-controls="stay-popup" aria-label="Start date" autocomplete="off" placeholder="Start date"
		value={formatDisplay(start, FORMAT)} data-slean-part="input" />
	<span data-slean-part="separator" aria-hidden="true"></span>
	<input type="text" role="combobox" aria-haspopup="dialog" aria-expanded="false"
		aria-controls="stay-popup" aria-label="End date" autocomplete="off" placeholder="End date"
		value={formatDisplay(end, FORMAT)} data-slean-part="input" />
	<button type="button" tabindex="-1" aria-label="Clear" data-slean-part="clear"></button>
	<span data-slean-part="icon" aria-hidden="true"></span>
	<div id="stay-popup" popover="manual" role="dialog" aria-labelledby="stay-label"
		data-slean-part="popup">
		<div data-slean="calendar" data-slean-mode="range" data-slean-month="2026-09"
			data-slean-value="2026-09-10/2026-09-18" data-slean-input="stay-start stay-end">
			<Month id="stay-cal" month="2026-09" months={2}
				options={{ mode: 'range', value: '2026-09-10/2026-09-18' }} />
		</div>
		<div data-slean-part="footer">
			{#each presets as [label, value] (label)}
				<button type="button" data-slean-part="preset" data-slean-value={value}>{label}</button>
			{/each}
		</div>
	</div>
</div>

Display format

The text input shows the date in data-slean-format (YYYY, MM, DD, M, D and literal separators), else in the numeric pattern of the nearest lang from dateFormat(). The native input keeps the ISO value whatever the text shows, so the form submits 2026-09-28. Render the text on the server with formatDisplay(value, format), the function the behavior writes it with.

<!-- The display format is data-slean-format, else the numeric pattern of the nearest lang:
     dateFormat('tr') is DD.MM.YYYY, dateFormat('en-US') MM/DD/YYYY, dateFormat('sv') YYYY-MM-DD. -->
<div lang="tr">
	<div id="due" data-slean="date-picker">…</div>
</div>

<!-- Typing is read in the order of the format's fields; any run of non-digits separates them,
     so 28.9.2026, 28/09/2026 and 2026-09-28 all read as 2026-09-28 in DD.MM.YYYY. -->

Testing

• packages/primitives/src/date-picker/contract.md the test cases of the contract: tests/date-picker.test.ts (happy-dom) and a Playwright spec on the playground’s /primitives/date-picker page
• apps/playground/src/routes/primitives/date-picker/+page.svelte the playground fixtures: a date in DD.MM.YYYY, an empty picker and a range with presets
• apps/playground/tests/primitives/nested.spec.ts a date picker inside a modal dialog: the popup above the dialog, keyboard and pointer choices, Escape closing the popup before the dialog
• apps/playground/tests/stress/memory.spec.ts 200 open/close cycles through the grid: heap, DOM nodes and listeners back at baseline, one scoped listener per open
• fixtures/date-picker-only consumer build: the date picker and calendar registrations ship with one kernel; tabs, menu, listbox, combobox and select are absent
• packages/primitives/tests/calendar.test.ts Vitest: the model, keyboard across months, RTL, modes, min/max, inputs, 1000 calendars
• apps/playground/tests/primitives/calendar.spec.ts Playwright: the grid, the date picker and the range picker in Chromium
• packages/styles/tests static checks of the stylesheet (layers, tokens, specificity, dark parity)
• apps/playground/tests/primitives/a11y.spec.ts axe on every playground page and on open dialog, popover and menu states

Source

• packages/primitives/src/date-picker/contract.md the contract in prose: semantics, keyboard, focus, ARIA, SSR, JS-disabled behavior
• packages/primitives/src/date-picker/contract.ts typed constants: name, tier, base, parts, options, events
• packages/primitives/src/date-picker/behavior.ts the behavior definition, openDatePicker(), closeDatePicker(), setDatePickerValue()
• packages/primitives/src/date-picker/format.ts dateFormat(), formatDisplay() and parseDisplay(), pure and SSR-safe
• packages/primitives/src/date-picker/register.ts the registration module
• packages/primitives/src/date-picker/validate.ts development validation messages
• packages/styles/css/control.css the control shell shared with the select and the combobox
• packages/styles/css/date-picker.css the optional stylesheet