Calendar
June 2026
A WAI-ARIA date grid with keyboard navigation, selection, appointment dots and per-day prices. Switch between month, two-month, week, three-day, day and year views.
Import
Section titled “Import”<script> import Calendar from "@invisible-ui/svelte/Calendar.svelte";</script><script setup> import { Calendar } from "@invisible-ui/vue";</script>import { Calendar } from "@invisible-ui/react";<script type="module"> import "@invisible-ui/elements/define";</script>
<ds-calendar></ds-calendar>In Elements, names come from Intl. Events and prices are properties:
<ds-calendar value="2026-06-15" views="month week day"></ds-calendar><script type="module"> const calendar = document.querySelector("ds-calendar"); calendar.events = [{ date: "2026-06-18", label: "Review", tone: "warning" }]; calendar.addEventListener("change", (event) => console.log(event.detail.value));</script>| Prop | Type | Default | Description |
|---|---|---|---|
value | string | null | null | |
focusedDate | string | undefined | undefined | |
view | CalendarView | "month" | |
weekStartsOn | WeekStart | undefined | undefined | First day of the week, 0 = Sunday … 6 = Saturday. Defaults to the locale's first day of the week (from locale, else the provider's). |
min | string | undefined | undefined | |
max | string | undefined | undefined | |
locale | string | undefined | undefined | BCP-47 locale for month/weekday names. |
events | CalendarEvent[] | [] | Appointment dots ({ date, label?, tone? }), keyed by date. |
prices | Record<string, string> | {} | Per-day price label, keyed by ISO date. |
maxDots | number | 3 | Max appointment dots before a "+N" overflow marker. |
yearColumns | number | 1 | Mini-months per row in the year view. |
views | CalendarView[] | ["month"] | Views offered in the built-in switcher (one entry = no switcher). |
viewLabels | Partial<Record<CalendarView, string>> | {} | Override the switcher labels per view. |
showToday | boolean | true | Show the "today" shortcut in the header. |
prevLabel | string | undefined | undefined | Header control labels (fall back to the i18n catalog). |
nextLabel | string | undefined | undefined | Header control labels (fall back to the i18n catalog). |
todayLabel | string | undefined | undefined | Header control labels (fall back to the i18n catalog). |
viewsLabel | string | undefined | undefined | Accessible name for the view switcher. |
label | string | undefined | undefined | Accessible name for the grid (falls back to the i18n catalog). |
mode | "single" | "range" | "single" | Single date, or a start–end range. |
rangeStart | string | null | null | Range endpoints (when mode="range"). |
rangeEnd | string | null | null | Range endpoints (when mode="range"). |
onValueChange | ((iso: string) => void) | undefined | undefined | Called when the selected date changes. |
onFocusChange | ((iso: string) => void) | undefined | undefined | Called when the focused date changes. |
onViewChange | ((view: CalendarView) => void) | undefined | undefined | Called when the active view changes. |
onRangeChange | ((start: string | null, end: string | null) => void) | undefined | undefined | Called when the range changes. |
day | Snippet<[CalendarDayContext]> | undefined | undefined | Custom content of a day in the grid views, replacing the number, dots and price. |
| Prop | Type | Default | Description |
|---|---|---|---|
modelValue | string | null | undefined | Selected date (ISO YYYY-MM-DD); bindable with v-model. |
value | string | null | null | |
focusedDate | string | undefined | |
view | CalendarView | "month" | |
weekStartsOn | WeekStart | undefined | First day of the week (0 = Sunday). Defaults to the locale's first day of the week. |
min | string | undefined | |
max | string | undefined | |
locale | string | undefined | BCP-47 locale for month and weekday names. Defaults to the runtime locale. |
events | CalendarEvent[] | () => [] | Appointment dots, keyed by their date. |
prices | Record<string, string> | () => ({}) | Per-day price label, keyed by ISO date (e.g. { "2026-06-25": "€120" }). |
maxDots | number | 3 | Maximum dots rendered before a "+N" overflow marker (grid views). |
yearColumns | number | 1 | Year view: how many mini-months per row. |
views | CalendarView[] | () => ["month"] | Views offered in the built-in switcher. With one entry no switcher shows. |
viewLabels | Partial<Record<CalendarView, string>> | () => ({}) | Override the switcher labels per view. |
showToday | boolean | true | |
prevLabel | string | undefined | |
nextLabel | string | undefined | |
todayLabel | string | undefined | |
viewsLabel | string | undefined | |
label | string | undefined | Accessible name for the grid. |
mode | CalendarMode | "single" | |
rangeStart | string | null | null | Range endpoints (ISO), used when mode="range". |
rangeEnd | string | null | null | |
onValueChange | (value: string) => void | undefined | |
onFocusChange | (value: string) => void | undefined | |
onViewChange | (view: CalendarView) => void | undefined | |
onRangeChange | (start: string | null, end: string | null) => void | undefined |
| Event | Payload |
|---|---|
update:modelValue | value: string |
Slots: day.
| Prop | Type | Default | Description |
|---|---|---|---|
value | string | null | null | Initial (uncontrolled) or current (controlled) selected date, ISO YYYY-MM-DD. |
focusedDate | string | — | The date that drives what is shown and where focus sits. |
view | CalendarView | "month" | Initial (uncontrolled) or current (controlled) view. |
weekStartsOn | WeekStart | — | First day of the week, 0 = Sunday to 6. |
min | string | — | Earliest selectable date (ISO), inclusive. |
max | string | — | Latest selectable date (ISO), inclusive. |
locale | string | — | BCP-47 locale for month and weekday names. Defaults to the provider's locale. |
events | CalendarEvent[] | — | Appointment dots, keyed by their date. |
prices | Record<string, string> | {} | Per-day price label, keyed by ISO date (e.g. { "2026-06-25": "€120" }). |
maxDots | number | 3 | Maximum dots rendered before a "+N" overflow marker (grid views). |
yearColumns | number | 1 | Year view: how many mini-months per row. |
views | CalendarView[] | ["month"] | Views offered in the built-in switcher. With one entry no switcher shows. |
viewLabels | Partial<Record<CalendarView, string>> | {} | Override the switcher labels per view. |
showToday | boolean | true | |
prevLabel | string | — | Label of the previous button. Defaults to the catalog's. |
nextLabel | string | — | Label of the next button. Defaults to the catalog's. |
todayLabel | string | — | Text of the Today button. Defaults to the catalog's. |
viewsLabel | string | — | Name of the view switcher. Defaults to the catalog's. |
label | string | — | Accessible name for the grid. Defaults to the catalog's. |
mode | CalendarMode | "single" | Selection mode: a single date, or a start-to-end range. |
rangeStart | string | null | null | Range start (ISO), used when mode="range". |
rangeEnd | string | null | null | Range end (ISO), used when mode="range". |
onValueChange | (value: string) => void | — | Called when the user selects a date (single mode). |
onFocusChange | (value: string) => void | — | Called when the user moves the focused date. |
onViewChange | (view: CalendarView) => void | — | Called when the user changes the view. |
onRangeChange | (start: string | null, end: string | null) => void | — | Called after each pick in range mode, with a null end while the range is half made. |
renderDay | (day: CalendarDayContext) => ReactNode | — | Custom content of a day in the grid views, replacing the number, dots and price. |
| Attribute | Reactive | Description |
|---|---|---|
value | yes | ISO YYYY-MM-DD |
focused-date | yes | |
view | yes | |
views | yes | space-separated list for the switcher |
week-starts-on | yes | 0 = Sunday to 6 |
min | yes | |
max | yes | |
locale | yes | |
label | yes | |
prev-label | yes | |
next-label | yes | |
today-label | yes | |
views-label | yes | |
show-today | yes | "false" hides it |
mode | yes | single|range |
range-start | yes | |
range-end | yes | |
max-dots | yes | |
year-columns | yes |
Reactive attributes re-render the element when they change after the first render.
Properties: value, focusedDate, view, rangeStart, rangeEnd, events (CalendarEvent[]), prices (ISO date to label), viewLabels.
Emits: change (detail.value), range-change (detail.start, detail.end), focus-change (detail.value), view-change (detail.view).
Accessibility
Section titled “Accessibility”role="grid"of day buttons with roving tabindex; arrows move by day/week, Home/End to the week edges, PageUp/PageDown by month (Shift = year), Enter/Space selects.- In right-to-left text ArrowLeft moves to the next day and ArrowRight to the previous one, and the previous and next arrows are mirrored.
- The period title is announced (
aria-live); out-of-range days arearia-disabled; today isaria-current="date". - In
mode="range"every day of the range, the two ends and the days between, is a selected cell (aria-selected). The ends add “range start” and “range end” to the day’s name, and a day with events adds the event count. These texts come from the message catalog, so a Locale Provider can translate them.
First day of the week
Section titled “First day of the week”Without weekStartsOn, every adapter starts the week on the locale’s first
day from CLDR week data, read from the language and the region: Sunday for
en-US, Monday for it-IT and en-GB, Saturday for ar-EG. The locale is
the calendar’s locale, else the
Locale Provider’s,
else the page’s lang, else the international default, which starts on
Monday (see
Default locale).
The browser’s own language never decides. Set weekStartsOn (0 = Sunday … 6
= Saturday) to choose the day yourself.
Example
Section titled “Example”<Calendar value="2026-06-15" views={["month", "week", "day"]} events={[{ date: "2026-06-18", label: "Review", tone: "warning" }]} prices={{ "2026-06-12": "€120" }}/>In React, onValueChange reports a pick, mode="range" reports both ends
through onRangeChange, and renderDay replaces a day’s content:
<Calendar value={day} views={["month", "week"]} events={events} onValueChange={setDay} />Themeable via --ds-calendar-*.