Primitives Date and time
Calendar
An inline month grid for choosing one date, a range or several dates, shown on the page rather than in a form field.
Markdown version of this page, for assistants (Markdown for AI)
On this page
September 2026
| Mon | Tue | Wed | Thu | Fri | Sat | Sun |
|---|---|---|---|---|---|---|
Code
<script lang="ts">
import '@svelte-lean/styles/calendar.css';
import { calendarHTML } from '@svelte-lean/primitives/calendar';
// The header and the 42 cells, rendered once: after hydration the behavior owns them.
const html = calendarHTML({ id: 'due', value: '2026-09-28' });
</script>
<div id="due" data-slean="calendar" data-slean-month="2026-09" data-slean-value="2026-09-28">
{@html html}
</div>Examples
Range
September 2026
| Mon | Tue | Wed | Thu | Fri | Sat | Sun |
|---|---|---|---|---|---|---|
Code
<script lang="ts">
import { calendarHTML } from '@svelte-lean/primitives/calendar';
const html = calendarHTML({ id: 'trip', mode: 'range', value: '2026-09-10/2026-09-18' });
</script>
<div id="trip" data-slean="calendar" data-slean-mode="range" data-slean-month="2026-09"
data-slean-value="2026-09-10/2026-09-18">
{@html html}
</div>Two months
September 2026
October 2026
| Mon | Tue | Wed | Thu | Fri | Sat | Sun |
|---|---|---|---|---|---|---|
| Mon | Tue | Wed | Thu | Fri | Sat | Sun |
|---|---|---|---|---|---|---|
Code
<script lang="ts">
import { calendarHTML } from '@svelte-lean/primitives/calendar';
// Two grids and two titles: the second grid shows the month after data-slean-month.
const html = calendarHTML({ id: 'stay', mode: 'range', months: 2, month: '2026-09',
value: '2026-09-24/2026-10-06' });
</script>
<div id="stay" data-slean="calendar" data-slean-mode="range" data-slean-month="2026-09"
data-slean-value="2026-09-24/2026-10-06">
{@html html}
</div>Multiple dates
September 2026
| Mon | Tue | Wed | Thu | Fri | Sat | Sun |
|---|---|---|---|---|---|---|
Code
<script lang="ts">
import { calendarHTML } from '@svelte-lean/primitives/calendar';
// The value is a space-separated list of dates.
const html = calendarHTML({ id: 'shifts', mode: 'multiple',
value: '2026-09-02 2026-09-09 2026-09-16' });
</script>
<div id="shifts" data-slean="calendar" data-slean-mode="multiple" data-slean-month="2026-09"
data-slean-value="2026-09-02 2026-09-09 2026-09-16">
{@html html}
</div>In a form
Code
<script lang="ts">
import { calendarHTML } from '@svelte-lean/primitives/calendar';
const html = calendarHTML({ id: 'delivery', value: '2026-09-28' });
</script>
<!-- A date input inside the root, named by data-slean-input, carries the form value: the calendar
writes it, and follows a form reset and setValue() on it. -->
<form>
<div id="delivery" data-slean="calendar" data-slean-month="2026-09"
data-slean-value="2026-09-28" data-slean-input="delivery-date">
<input id="delivery-date" type="date" name="delivery" value="2026-09-28" hidden />
{@html html}
</div>
<button type="reset" data-slean="button" data-variant="outlined" data-color="neutral">Reset</button>
</form>Reading the value
September 2026
| Mon | Tue | Wed | Thu | Fri | Sat | Sun |
|---|---|---|---|---|---|---|
Chosen: 2026-09-28.
Code
<script lang="ts">
import { on } from 'svelte/events';
import { calendarHTML, type CalendarChangeDetail } from '@svelte-lean/primitives/calendar';
const html = calendarHTML({ id: 'chosen', value: '2026-09-28' });
let chosen = $state('2026-09-28');
let note = $state('');
// slean:change is cancelable and dispatched before the calendar writes anything.
const guard = (node: HTMLElement) =>
on(node, 'slean:change', (event) => {
const { value } = (event as CustomEvent<CalendarChangeDetail>).detail;
if (value.endsWith('-13')) {
event.preventDefault();
note = 'The 13th is refused.';
} else {
chosen = value;
note = '';
}
});
</script>
<div id="chosen" data-slean="calendar" data-slean-month="2026-09" data-slean-value="2026-09-28"
{@attach guard}>
{@html html}
</div>
<p role="status">Chosen: {chosen}. {note}</p>Jump to month and year
September 1990
| Mon | Tue | Wed | Thu | Fri | Sat | Sun |
|---|---|---|---|---|---|---|
Code
<script lang="ts">
import { calendarHTML } from '@svelte-lean/primitives/calendar';
// selects: true writes the month and year selects into the header (the year buttons give way to
// them). The years run from min's to max's (1900 to 2099 without bounds); yearRange: [2026,
// 1926] would list the newest first.
const html = calendarHTML({ id: 'birth', value: '1990-09-15', min: '1926-01-01',
max: '2026-12-31', selects: true });
</script>
<div id="birth" data-slean="calendar" data-slean-month="1990-09" data-slean-value="1990-09-15"
data-slean-min="1926-01-01" data-slean-max="2026-12-31">
{@html html}
</div>Bounds, off days and locale
Eylül 2026
| Pzt | Sal | Çar | Per | Cum | Cmt | Paz |
|---|---|---|---|---|---|---|
Code
<script lang="ts">
import { calendarHTML } from '@svelte-lean/primitives/calendar';
// The same options as the attributes: the first render and the behavior agree.
const html = calendarHTML({ id: 'booking', locale: 'tr', month: '2026-09',
min: '2026-09-07', max: '2026-10-20', disabledWeekdays: [0, 6] });
</script>
<!-- The locale is the nearest lang: titles, weekday and button names in Turkish. -->
<div lang="tr">
<div id="booking" data-slean="calendar" data-slean-month="2026-09" data-slean-min="2026-09-07"
data-slean-max="2026-10-20" data-slean-offdays="0 6">
{@html html}
</div>
</div>Usage
Install @svelte-lean/primitives and @svelte-lean/styles. With @svelte-lean/vite the behavior registers itself for every data-slean="calendar"; without it, import the register module once.
npm install @svelte-lean/primitivespnpm add @svelte-lean/primitivesyarn add @svelte-lean/primitivesbun add @svelte-lean/primitivesimport '@svelte-lean/primitives/calendar/register';import '@svelte-lean/styles/calendar.css';Write the root with its options and its id, and render the inside with calendarHTML({ id, …the same options }) once (a const): after hydration the behavior rewrites the cells, so the application must not write them again. Listen to slean:change (onslean:change) for the chosen value and slean:navigate for the shown month.
For a form value, put a date input inside the root and name it with data-slean-input: the calendar writes it and follows a form reset and setValue(). For a field with a popup, use the Date picker, which generates its calendar.
Anatomy
| Part | Element | data-slean-part | Required | Notes |
|---|---|---|---|---|
| root | <div data-slean="calendar"> | – | yes | Options: data-slean-value, -month, -mode (single, range, multiple), -weekstart, -min, -max, -offdays, -input. |
| header | <div> | header | styles only | Groups the year and month buttons and the titles on one row above the grids; the flat markup without it keeps its layout. |
| title | <h2 id="…"> | title | yes | The month and year, one per grid; each grid is labelled by its id. Rewritten on navigation. The first title is hidden visually while the month and year selects are present. |
| previous-year | <button type="button" aria-label="Previous year"> | previous-year | no | Shows the same month a year earlier; aria-disabled="true" past min. |
| previous | <button type="button" aria-label="Previous month"> | previous | no | aria-disabled="true" when no earlier month holds a selectable day. |
| next | <button type="button" aria-label="Next month"> | next | no | aria-disabled="true" when no later month holds a selectable day. |
| next-year | <button type="button" aria-label="Next year"> | next-year | no | Shows the same month a year later; aria-disabled="true" past max. |
| month | <select aria-label="Month"> | month | no | Twelve options valued 1 to 12 (calendarMonthNames()), written by calendarHTML({ selects: true }); jumps to that month of the shown year. Months outside min and max are disabled for the shown year. |
| year | <select aria-label="Year"> | year | no | Options valued by year (calendarYears(); calendarHTML({ selects: true }) lists min’s to max’s year, 1900 to 2099 without them, or yearRange); jumps to the shown month of that year, clamped to min and max. Shows no value while the shown year has no option. |
| grid | <table role="grid" aria-labelledby="…"> | grid | yes | One per month shown (two for a range picker). Column headers from calendarMonth().weekdays; aria-multiselectable="true" in multiple mode. |
| day | <td role="gridcell"><button data-slean-value="YYYY-MM-DD"></button></td> | day | yes | Exactly 42 per grid. aria-selected on the cell; aria-current="date", aria-disabled, data-slean-outside, data-slean-edge and data-slean-preview on the button. |
Keyboard
| Key | When | Result |
|---|---|---|
| Enter/Space | focus on a day | Chooses it (native activation) |
| ArrowLeft/ArrowRight | focus on a day | Previous or next day, into the neighbouring month; swapped under dir="rtl" |
| ArrowUp/ArrowDown | focus on a day | Same weekday a week earlier or later |
| Home/End | focus on a day | First or last day of the week |
| PageUp/PageDown | focus on a day | Same day of the previous or next month, clamped to its last day |
| Shift+PageUp/Shift+PageDown | focus on a day | Same day of the previous or next year |
| ArrowUp/ArrowDown | focus on the month or year select | The platform’s select keyboard; each change shows that month |
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 compact month and year selects, 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. data-color on the root or an ancestor colors the selected days, today's ring and the range band (primary by default). The tokens it reads:
| Token | Default (light) | Applies to |
|---|---|---|
--slean-space-6 | calc(var(--slean-spacing) * 6) | column-gap |
--slean-space-2 | calc(var(--slean-spacing) * 2) | row-gap, padding, column-gap, padding-inline, padding-block-end, background-position |
--slean-space-3 | calc(var(--slean-spacing) * 3) | padding, margin-inline |
--slean-fg | var(--slean-neutral-12) | color |
--slean-color-scheme | light | color-scheme |
--slean-text-sm | 0.875rem | font-size |
--slean-border | var(--slean-neutral-6) | border-block-end |
--slean-font-weight-semibold | 600 | font-weight |
--slean-leading | 1.5 | line-height |
--slean-control-height-sm | 2rem | min-block-size, inline-size, block-size, min-inline-size |
--slean-control-border | var(--slean-border-strong) | border |
--slean-radius-sm | calc(var(--slean-radius) * 0.6) | border-radius |
--slean-control-icon | var(--slean-fg-muted) | background |
--slean-control-bg | var(--slean-surface) | background |
--slean-fg-muted | var(--slean-neutral-11) | color |
--slean-duration-fast | 100ms | transition |
--slean-ease | cubic-bezier(0.2, 0, 0, 1) | transition |
--slean-icon-chevron-left | url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'%3E%3Cpath d='M10 4L6 8l4 4' stroke='black' stroke-width='1.5' stroke-linecap='round' stroke-linejoin='round' fill='none'/%3E%3C/svg%3E") | mask |
--slean-icon-chevron-right | url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'%3E%3Cpath d='M6 4l4 4-4 4' stroke='black' stroke-width='1.5' stroke-linecap='round' stroke-linejoin='round' fill='none'/%3E%3C/svg%3E") | mask-image |
--slean-icon-chevrons-left | url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'%3E%3Cpath d='M8 4L4 8l4 4M12 4L8 8l4 4' stroke='black' stroke-width='1.5' stroke-linecap='round' stroke-linejoin='round' fill='none'/%3E%3C/svg%3E") | mask-image |
--slean-icon-chevrons-right | url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'%3E%3Cpath d='M4 4l4 4-4 4M8 4l4 4-4 4' stroke='black' stroke-width='1.5' stroke-linecap='round' stroke-linejoin='round' fill='none'/%3E%3C/svg%3E") | mask-image |
--slean-color-main | var(--slean-primary-main) | border-color, background, border-block |
--slean-color-contrast-text | var(--slean-primary-contrast-text) | color |
--slean-color-soft | var(--slean-primary-soft) | background |
--slean-muted | var(--slean-neutral-3) | background |
--slean-control-border-hover | initial | border-color |
--slean-control-height-md | 2.25rem | min-inline-size, block-size |
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).
Under the hood
Runtime and size
- Tier
- 1 · Delegated micro-behavior
- Behavior JS
- 4594 B brotli · 5021 B gzip ·
packages/· methodprimitives/ artifacts/ size.json - Platform features
role="grid",aria-selected,aria-current="date",Intl.DateTimeFormat,Intl.RelativeTimeFormat,:dir(rtl)- Shared listeners
- click, keydown, change, reset, pointerover, pointerout
- Per-instance listeners
- none
- Lazy state
- none
- Native base
role=grid of day buttons in a <table>
The calendar registers click, keydown, change, reset, pointerover and pointerout handlers with the shared router; change comes from the month and year selects and the inputs inside the root, reset from their form, and the pointer handlers draw the preview of an open range (data-slean-preview). 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).
Why this implementation
The platform has a date input with its own picker, and that is the native path for entering a date (see Input). What it does not have is an inline month: a grid to look at, choose from and move through by keyboard. A visible month must be in the server markup, so calendarHTML() returns the header and the 42 cells as a string, pure and deterministic, for {@html} in any template on the server and in the browser; calendarMonth() returns the model for a template that renders the cells itself.
The behavior 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.
The browser owns
- the buttons: focus, Enter and Space activation, the accessible name from aria-label
- the table and its grid, gridcell and column header roles
- the month, weekday and date names in every locale (Intl.DateTimeFormat)
- the month and year selects: their picker, keyboard and accessible names
- the click, keydown, change, reset, pointerover and pointerout events routed to the behavior
Svelte Lean owns
- calendarHTML(): the header and the 42 cells of one or two months as a string for {@html}, the same on the server and in the browser; calendarMonth(): the model for a template that renders the cells itself
- calendarLabels(): the buttons’ names in the locale from Intl.RelativeTimeFormat, the selects’ from Intl.DisplayNames
- choosing a day in single, range and multiple mode, min, max and off days
- two months side by side for a range, and data-slean-preview on the days a click would add to an open range
- arrow keys, Home and End, PageUp and PageDown across months and years; the month and year buttons
- calendarMonthNames() and calendarYears() for the month and year selects; showing the chosen month clamped to min and max, and writing the selects back on every month change
- rewriting the same 42 cells when the month changes; the roving tabindex
- writing the inputs named by data-slean-input and closing a surrounding popover; following setValue() and a form reset of the inputs inside the root
- the cancelable slean:change and slean:navigate events, development validation, calendar.css
Accessibility
role="grid"labelled by the title;role="gridcell"witharia-selectedon each cell;aria-multiselectable="true"in multiple mode.- Each day button is named by its full date in the locale (
aria-label); today carriesaria-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, in the locale by default: "Last month", "Next year") andaria-disabled="true"pastminormax; their icons are CSS masks with no text. - The month and year selects are native
<select>elements with names (aria-label); the grid keeps the title as its name while the styles hide the title visually.
Platform features
| Feature | Baseline | Outside the target |
|---|---|---|
Intl.DateTimeFormat | Widely available (Baseline since 2017) | Not applicable |
Intl.RelativeTimeFormat | Baseline 2020 | Not applicable within the support policy |
:dir() | Baseline 2023 | The month chevrons do not mirror under RTL |
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: its native date input keeps working.
Server rendering and hydration
calendarHTML() and calendarMonth() are pure; render the inside on the server with the same options the attributes carry. Pass today explicitly (or null on a prerendered page, and the behavior marks today in the browser) if a page may be rendered and hydrated on different days. calendarHTML() with selects: true writes the month and year selects with the shown month selected; a template renders them with calendarMonthNames(locale) and calendarYears(min, max).
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.
Compatibility
Nothing beyond buttons, native selects, tables, ARIA grid roles and Intl.DateTimeFormat, all widely available (Intl.DisplayNames names the selects where it exists, Baseline 2022). Week numbers and month and year views are not part of the primitive: the month and year selects jump to a month instead of a year view. A time is the Date picker's, over a datetime-local input.
Tests and source
packages/primitives/tests/calendar.test.tsVitest: the model, calendarHTML(), keyboard across months, RTL, modes, min/max, inputs, setValue() and reset, 1000 calendarsapps/playground/tests/primitives/calendar.spec.tsPlaywright: the grid, the range picker, the selects and a calendarHTML() calendar in a form in Chromiumpackages/styles/testsstatic checks of the stylesheet (layers, tokens, specificity, dark parity)
packages/primitives/src/calendar/contract.mdthe contract in prose: semantics, keyboard, focus, ARIA, SSR, JS-disabled behaviorpackages/primitives/src/calendar/contract.tstyped constants: name, tier, base, parts, options, eventspackages/primitives/src/calendar/model.tscalendarMonth() and the date arithmetic, pure and SSR-safepackages/primitives/src/calendar/markup.tscalendarHTML() and calendarLabels(), pure and SSR-safepackages/primitives/src/calendar/behavior.tsthe behavior definitionpackages/primitives/src/calendar/register.tsthe registration modulepackages/styles/css/calendar.cssthe optional stylesheet