Calendar

Example

<div data-slean="calendar" data-slean-month="2026-09" data-slean-value="2026-09-28">
	<div data-slean-part="header">
		<button type="button" data-slean-part="previous-year" aria-label="Previous year"></button>
		<button type="button" data-slean-part="previous" aria-label="Previous month"></button>
		<h3 id="due-title-0" data-slean-part="title">September 2026</h3>
		<button type="button" data-slean-part="next" aria-label="Next month"></button>
		<button type="button" data-slean-part="next-year" aria-label="Next year"></button>
	</div>
	<table role="grid" data-slean-part="grid" aria-labelledby="due-title-0">
		<thead>
			<tr>
				<th scope="col" abbr="Monday">Mon</th>
				<!-- … Tuesday to Sunday -->
			</tr>
		</thead>
		<tbody>
			<tr>
				<td role="gridcell" aria-selected="false">
					<button type="button" data-slean-part="day" data-slean-value="2026-08-31"
						aria-label="Monday, August 31, 2026" data-slean-outside tabindex="-1">31</button>
				</td>
				<td role="gridcell" aria-selected="false">
					<button type="button" data-slean-part="day" data-slean-value="2026-09-01"
						aria-label="Tuesday, September 1, 2026" tabindex="-1">1</button>
				</td>
				<!-- … 42 cells in six rows; the chosen day has aria-selected="true" on its cell
				     and tabindex="0" on its button -->
			</tr>
		</tbody>
	</table>
</div>

<!-- Month.svelte: the inside of a calendar root, rendered once. -->
<script lang="ts">
	import { untrack } from 'svelte';
	import { addMonths, calendarMonth, type CalendarOptions } from '@svelte-lean/primitives/calendar';

	let { id, month, options = {}, months = 1 }: {
		id: string; month: string; options?: CalendarOptions; months?: 1 | 2;
	} = $props();

	// After hydration the calendar behavior owns the cells and rewrites them when the month or
	// the selection changes, so the application renders them once and never again.
	const models = untrack(() =>
		Array.from({ length: months }, (_, i) => calendarMonth(addMonths(month, i), options))
	);
</script>

<div data-slean-part="header">
	<button type="button" data-slean-part="previous-year" aria-label="Previous year"></button>
	<button type="button" data-slean-part="previous" aria-label="Previous month"></button>
	{#each models as model, i (i)}
		<h3 id="{id}-title-{i}" data-slean-part="title">{model.title}</h3>
	{/each}
	<button type="button" data-slean-part="next" aria-label="Next month"></button>
	<button type="button" data-slean-part="next-year" aria-label="Next year"></button>
</div>
{#each models as model, i (i)}
	<table role="grid" data-slean-part="grid" aria-labelledby="{id}-title-{i}">
		<thead>
			<tr>
				{#each model.weekdays as w (w.long)}<th scope="col" abbr={w.long}>{w.short}</th>{/each}
			</tr>
		</thead>
		<tbody>
			{#each [0, 1, 2, 3, 4, 5] as week (week)}
				<tr>
					{#each model.days.slice(week * 7, week * 7 + 7) as day, d (d)}
						<td role="gridcell" aria-selected={day.selected}>
							<button
								type="button"
								data-slean-part="day"
								data-slean-value={day.date}
								aria-label={day.label}
								aria-disabled={day.disabled ? 'true' : undefined}
								aria-current={day.today ? 'date' : undefined}
								data-slean-outside={day.outside ? '' : undefined}
								data-slean-edge={day.edge ?? undefined}
								tabindex={day.tabbable && i === 0 ? 0 : -1}>{day.day}</button
							>
						</td>
					{/each}
				</tr>
			{/each}
		</tbody>
	</table>
{/each}

<!-- +page.svelte: the root with its static marker, where @svelte-lean/vite finds it. -->
<script lang="ts">
	import '@svelte-lean/styles/calendar.css';
	import Month from './Month.svelte';
</script>

<div data-slean="calendar" data-slean-month="2026-09" data-slean-value="2026-09-28">
	<Month id="due" month="2026-09" options={{ value: '2026-09-28' }} />
</div>

Why this implementation exists

The platform has a date input with its own picker, and that is the native path for entering a date (see Date field). What it does not have is an inline month: a grid to look at, choose from and move through by keyboard. Rendering 42 days is a template’s job, so calendarMonth() returns them, pure and deterministic, for the server and for any template.

The behavior has little to do and keeps nothing of its own. The shown month is data-slean-month, the selection is data-slean-value, the chosen cells carry aria-selected and one day holds tabindex="0". When the month changes, the same 42 buttons get new values, labels and states; no element is created or removed, so markup Svelte rendered stays the markup Svelte owns.

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

import '@svelte-lean/styles/calendar.css';

Render the root with its options, the header (year and month buttons, the title) and the 42 cells from calendarMonth(month, options). Pass the same options to the function and to the attributes. Listen to slean:change for the chosen value and slean:navigate for the shown month.

Render the cells once (untrack in Svelte): after hydration the behavior rewrites them when the month or the selection changes, so a later render of the application must not write them again.

For a value entered in a form, use the Date picker: its native date input holds the value and the calendar sits in its popup; the calendar alone has no form value.

<script lang="ts">
	import type { CalendarChangeDetail } from '@svelte-lean/primitives/calendar';

	let root: HTMLElement;
	let chosen = $state('2026-09-28');

	$effect(() => {
		// slean:change is cancelable and dispatched before the calendar writes anything.
		const onchange = (event: Event) => {
			const { value } = (event as CustomEvent<CalendarChangeDetail>).detail;
			if (value.endsWith('-13')) event.preventDefault();
			else chosen = value;
		};
		root.addEventListener('slean:change', onchange);
		return () => root.removeEventListener('slean:change', onchange);
	});
</script>

<div bind:this={root} data-slean="calendar" data-slean-value="2026-09-28">…</div>
<p>Chosen: {chosen}</p>

Anatomy

Runtime profile

The calendar registers click, keydown, pointerover and pointerout handlers with the shared router; the pointer handlers draw the preview of an open range. Its bytes, in the runtime block, are the production registration with the core kernel, the date model and the Intl formatting it calls. A thousand calendars keep one listener per type (tests/calendar.test.ts).

Accessibility contract

• role="grid" labelled by the title; role="gridcell" with aria-selected on each cell; aria-multiselectable="true" in multiple mode.
• Each day button is named by its full date in the locale (aria-label); today carries aria-current="date".
• Unavailable days carry aria-disabled="true": focusable so the keyboard can cross them, never chosen.
• One day is in the tab order; the arrow keys, Home, End, PageUp and PageDown move it, across months.
• The title is rewritten on every month change; announce it with aria-live="polite" on the title when the grid is the only focus.
• The year and month buttons have names (aria-label) and aria-disabled="true" past min or max; their icons are CSS masks with no text.

Keyboard

Platform features

Without JavaScript

The server-rendered month is visible and readable; days cannot be chosen and the month does not change. Where a value must be entered without JavaScript, use the Date picker composition: its native date input keeps working.

Server rendering

calendarMonth() is pure; render the grid on the server with the same options the attributes carry. Pass today explicitly if a page may be rendered and hydrated on different days.

Before hydration

Before the behavior loads, a click on a day does nothing and the arrow keys scroll. The registration attaches no per-root state, so the first event after hydration works on the server's markup directly.

Styling

calendar.css lays out the header and one or two grids, draws the year and month buttons with the chevron icon masks (mirrored under :dir(rtl)), the day buttons, today's ring, the selected cell, the soft band between range ends, the preview of an open range and the unavailable days. The tokens it reads:

State selectors the stylesheet targets, all from the platform or ARIA: :dir(rtl), :first-child, :hover, :last-child, [aria-current="date"], [aria-disabled="true"], [aria-selected="true"].

Variant attributes: data-slean-outside; data-slean-mode (range); data-slean-preview; data-slean-edge (start, end, both).

Compatibility notes

Nothing beyond buttons, tables, ARIA grid roles and Intl.DateTimeFormat, all widely available. Week numbers, month and year views, and time selection are not part of the primitive.

Examples

Range

data-slean-mode="range": the first choice opens the range, the second closes it (earlier dates become the start). While only the start is chosen, the days between it and the day under the pointer carry data-slean-preview. The value is an ISO 8601 interval, 2026-09-10/2026-09-18.

Left, a range; right, multiple dates (aria-multiselectable="true" on the grid).

Two months

Two grid parts and two title parts show the month of data-slean-month and the next one, as the range picker does. One day across both grids holds the tab stop; the month and year buttons and moving past the last grid shift both.

<!-- Two grids and two titles: the second grid shows the month after data-slean-month. -->
<div data-slean="calendar" data-slean-mode="range" data-slean-month="2026-09"
	data-slean-value="2026-09-10/2026-09-18">
	<Month id="stay" month="2026-09" months={2}
		options={{ mode: 'range', value: '2026-09-10/2026-09-18' }} />
</div>

Bounds, off days and locale

data-slean-min, -max and -offdays make days unavailable; the month buttons stop at the bounds. The locale is the nearest lang: this one is Turkish, starts on Monday and knows nothing else about Turkey.

<div
	data-slean="calendar"
	data-slean-mode="range"
	data-slean-value="2026-09-10/2026-09-18"
	data-slean-weekstart="0"
	data-slean-min="2026-09-01"
	data-slean-offdays="0 6"
>…</div>

Testing

• 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)

Source

• packages/primitives/src/calendar/contract.md the contract in prose: semantics, keyboard, focus, ARIA, SSR, JS-disabled behavior
• packages/primitives/src/calendar/contract.ts typed constants: name, tier, base, parts, options, events
• packages/primitives/src/calendar/model.ts calendarMonth() and the date arithmetic, pure and SSR-safe
• packages/primitives/src/calendar/behavior.ts the behavior definition
• packages/primitives/src/calendar/register.ts the registration module
• packages/styles/css/calendar.css the optional stylesheet