Calendar
There is one calendar, ds-calendar, and every way of drawing days is a mode of it.
- A month the way a list draws its items: seven days across, a week to a row, each day a hairline box four squares wide and four high. Its date stands on the first square, two lines of events below it and one square to spare. With
compact, a day is one square and the month becomes the small one, one of twelve in a year. Withpicker, it is a field that opens that small month to choose a date: see the picker. - A week, a day or a swimlane with
view, changed in the header withviews: see Swimlane for work that runs for weeks or months, a week to a square and a row to a piece of work. - Activity squares with
activity: the days as quiet squares, a week to a column a square wide, a day on which something happens filled with its colour. See Activity squares.
Design examples
Section titled “Design examples”A compact fixed calendar puts day numbers on the small square grid.
<section class="specimen">
<ds-calendar compact fixed selectable value="2026-10-14"></ds-calendar><ds-row class="line" ><ds-text literal tone="muted" size="small">Field visit: 14 October</ds-text></ds-row>
</section>
<style>
.specimen { width: 100%; min-width: 0; --cell: calc(20px * var(--sf, 1)); }
.specimen .line { width: 100%; }
.specimen .grow { flex: 1; min-width: 0; }
.specimen .muted { color: var(--ds-text-color-muted); }
.specimen .mono { --ds-typeface-regular: var(--ds-typeface-mono); font-variant-numeric: tabular-nums; }
.specimen .value { width: calc(4 * var(--cell)); text-align: right; }
.specimen .mark { display: inline-flex; align-items: flex-end; width: var(--cell); height: var(--ds-control-height); flex: 0 0 var(--cell); }
.specimen .columns { display: flex; flex-wrap: wrap; gap: var(--cell); }
.specimen .columns > * { min-width: 0; }
.specimen fieldset { border: 0; padding: 0; margin: 0; }
.specimen legend { padding: 0; }
.specimen label { display: flex; align-items: flex-end; gap: calc(var(--cell) / 2); min-height: var(--cell); }
.specimen ds-panel { height: calc(10 * var(--cell)); }
</style> Two months lit by how much was written each day, as a contribution graph.
<section class="specimen">
<div class="columns"><ds-calendar compact heat fixed no-today month="2026-06" label="Writing, June 2026" literal data-showcase-props="{"events": [{"title": "1 pages", "start": "2026-06-01", "count": 1}, {"title": "3 pages", "start": "2026-06-03", "count": 3}, {"title": "2 pages", "start": "2026-06-04", "count": 2}, {"title": "4 pages", "start": "2026-06-08", "count": 4}, {"title": "6 pages", "start": "2026-06-09", "count": 6}, {"title": "2 pages", "start": "2026-06-10", "count": 2}, {"title": "5 pages", "start": "2026-06-12", "count": 5}, {"title": "2 pages", "start": "2026-06-15", "count": 2}, {"title": "7 pages", "start": "2026-06-16", "count": 7}, {"title": "9 pages", "start": "2026-06-17", "count": 9}, {"title": "3 pages", "start": "2026-06-18", "count": 3}, {"title": "1 pages", "start": "2026-06-19", "count": 1}, {"title": "4 pages", "start": "2026-06-22", "count": 4}, {"title": "8 pages", "start": "2026-06-23", "count": 8}, {"title": "12 pages", "start": "2026-06-24", "count": 12}, {"title": "6 pages", "start": "2026-06-25", "count": 6}, {"title": "2 pages", "start": "2026-06-26", "count": 2}, {"title": "3 pages", "start": "2026-06-29", "count": 3}, {"title": "5 pages", "start": "2026-06-30", "count": 5}]}"></ds-calendar><ds-calendar compact heat fixed no-today month="2026-07" label="Writing, July 2026" literal data-showcase-props="{"events": [{"title": "2 pages", "start": "2026-07-01", "count": 2}, {"title": "6 pages", "start": "2026-07-02", "count": 6}, {"title": "1 pages", "start": "2026-07-04", "count": 1}, {"title": "3 pages", "start": "2026-07-07", "count": 3}, {"title": "9 pages", "start": "2026-07-08", "count": 9}, {"title": "4 pages", "start": "2026-07-09", "count": 4}, {"title": "1 pages", "start": "2026-07-11", "count": 1}, {"title": "7 pages", "start": "2026-07-12", "count": 7}, {"title": "10 pages", "start": "2026-07-13", "count": 10}, {"title": "2 pages", "start": "2026-07-14", "count": 2}, {"title": "5 pages", "start": "2026-07-17", "count": 5}, {"title": "3 pages", "start": "2026-07-18", "count": 3}, {"title": "11 pages", "start": "2026-07-19", "count": 11}, {"title": "1 pages", "start": "2026-07-20", "count": 1}, {"title": "2 pages", "start": "2026-07-23", "count": 2}, {"title": "8 pages", "start": "2026-07-24", "count": 8}, {"title": "6 pages", "start": "2026-07-25", "count": 6}, {"title": "4 pages", "start": "2026-07-26", "count": 4}, {"title": "1 pages", "start": "2026-07-29", "count": 1}, {"title": "3 pages", "start": "2026-07-30", "count": 3}, {"title": "9 pages", "start": "2026-07-31", "count": 9}]}"></ds-calendar></div><ds-row class="line" ><ds-text literal tone="muted" size="small">Pages written each day: the busier the day, the stronger it is lit.</ds-text></ds-row>
</section>
<style>
.specimen { width: 100%; min-width: 0; --cell: calc(20px * var(--sf, 1)); }
.specimen .line { width: 100%; }
.specimen .grow { flex: 1; min-width: 0; }
.specimen .muted { color: var(--ds-text-color-muted); }
.specimen .mono { --ds-typeface-regular: var(--ds-typeface-mono); font-variant-numeric: tabular-nums; }
.specimen .value { width: calc(4 * var(--cell)); text-align: right; }
.specimen .mark { display: inline-flex; align-items: flex-end; width: var(--cell); height: var(--ds-control-height); flex: 0 0 var(--cell); }
.specimen .columns { display: flex; flex-wrap: wrap; gap: var(--cell); }
.specimen .columns > * { min-width: 0; }
.specimen fieldset { border: 0; padding: 0; margin: 0; }
.specimen legend { padding: 0; }
.specimen label { display: flex; align-items: flex-end; gap: calc(var(--cell) / 2); min-height: var(--cell); }
.specimen ds-panel { height: calc(10 * var(--cell)); }
</style> (function mountShowcase(root) {
root.querySelectorAll("[data-showcase-props]").forEach((element) => {
const props = JSON.parse(element.dataset.showcaseProps);
Object.assign(element, props);
if (element.localName === "ds-sidebar") {
let items = props.items;
const render = () => {
let collapsedDepth;
const visible = items.filter((item) => {
const depth = item.depth ?? 0;
if (collapsedDepth !== void 0 && depth > collapsedDepth) return false;
collapsedDepth = item.expanded === false ? depth : void 0;
return true;
});
Object.assign(element, { items: visible });
};
element.addEventListener("sidebar-activate", (event) => {
const id = event.detail.id;
items = items.map((item) => ({ ...item, current: item.id === id }));
render();
});
element.addEventListener("sidebar-toggle", (event) => {
const { id, expanded } = event.detail;
items = items.map((item) => item.id === id ? { ...item, expanded } : item);
render();
});
}
});
root.querySelectorAll("ds-token-field").forEach((field) => {
field.addEventListener("ds-token-commit", (event) => {
const { text } = event.detail;
const input = field.querySelector("input");
if (!input || !text.trim()) return;
const token = document.createElement("ds-token");
token.setAttribute("value", text.trim());
token.setAttribute("label", text.trim());
token.setAttribute("remove-label", `Remove ${text.trim()}`);
field.insertBefore(token, input);
input.value = "";
input.dispatchEvent(new Event("input", { bubbles: true }));
});
field.addEventListener("ds-token-remove", (event) => {
const token = event.target;
if (token instanceof Element && token.localName === "ds-token") token.remove();
});
});
window.addEventListener("message", (event) => {
if (event.origin !== location.origin || event.source !== parent || event.data?.type !== "ds1-example-theme") return;
requestAnimationFrame(() => root.querySelectorAll("ds-chart, ds-spark, ds-bars").forEach((chart) => {
chart.refreshTheme?.();
}));
});
})(document); One picker chooses the stay: arrival and departure in the same month, written as one value.
<section class="specimen">
<ds-calendar picker label="Arrival and departure" literal name="stay" value="2026-11-04/2026-11-07"></ds-calendar>
</section>
<style>
.specimen { width: 100%; min-width: 0; --cell: calc(20px * var(--sf, 1)); }
.specimen .line { width: 100%; }
.specimen .grow { flex: 1; min-width: 0; }
.specimen .muted { color: var(--ds-text-color-muted); }
.specimen .mono { --ds-typeface-regular: var(--ds-typeface-mono); font-variant-numeric: tabular-nums; }
.specimen .value { width: calc(4 * var(--cell)); text-align: right; }
.specimen .mark { display: inline-flex; align-items: flex-end; width: var(--cell); height: var(--ds-control-height); flex: 0 0 var(--cell); }
.specimen .columns { display: flex; flex-wrap: wrap; gap: var(--cell); }
.specimen .columns > * { min-width: 0; }
.specimen fieldset { border: 0; padding: 0; margin: 0; }
.specimen legend { padding: 0; }
.specimen label { display: flex; align-items: flex-end; gap: calc(var(--cell) / 2); min-height: var(--cell); }
.specimen ds-panel { height: calc(10 * var(--cell)); }
</style> Try it
Section titled “Try it”Press a day to select it, or move with the arrow keys and Page Up and Page Down. The third event on a day folds into +2; press it to unfold them.
<ds-calendar selectable week-numbers></ds-calendar> const calendar = document.querySelector('ds-calendar');
calendar.events = [
{ title: 'Design review', start: '2026-10-03', time: '10:00', color: 'var(--ds-zenith-blue)' },
{ title: 'Launch', start: '2026-10-12', end: '2026-10-14', color: 'var(--ds-apple-green)' },
{ title: 'Dentist', start: '2026-10-12', time: '08:30' },
{ title: 'Dinner', start: '2026-10-12', time: '19:00', color: 'var(--ds-pink)' },
];
calendar.addEventListener('change', event => console.log(event.detail.value)); compact draws a month one square a day, as a year of months is drawn. With events, the days that have one keep the ink.
<ds-calendar compact selectable fixed></ds-calendar> heat lights each day by how much happens on it: the events’ counts added up, in four steps of the busiest day. Quiet days stay plain.
<ds-calendar compact heat fixed outside-days day-width="2"></ds-calendar> const calendar = document.querySelector('ds-calendar');
const month = calendar.shownMonth.slice(0, 7);
const counts = [0, 2, 5, 1, 0, 0, 3, 8, 4, 0, 1, 6, 12, 2, 0, 0, 7, 3, 9, 1, 0, 0, 2, 10, 5, 4, 0, 0, 1, 3, 6];
calendar.events = counts.flatMap((count, index) => count ? [{ title: count + ' changes', start: month + '-' + String(index + 1).padStart(2, '0'), count }] : []); Press a day to choose it; press another to end a range from it, and the pointer previews the end. The press after starts again. Each press fires change.
<ds-calendar compact selectable fixed outside-days day-width="2"></ds-calendar> Open it with a click, Enter or the down arrow. Press a first day and a last; press one day twice, or leave, for a single day. Escape closes it.
<div style="display:flex;flex-wrap:wrap;gap:var(--ds-unit)">
<ds-calendar picker label="When" literal name="when"></ds-calendar>
<ds-calendar picker label="Trip" literal name="trip" value="2026-10-21/2026-10-24"></ds-calendar>
</div> The swimlane: a week to each square across, a project to each row, one bar from its first week to its last. Calendar and Swimlane in the header change the view; the arrows move a month.
<ds-calendar views="month swimlane" view="swimlane" fixed></ds-calendar> const calendar = document.querySelector('ds-calendar');
calendar.viewNames = { month: 'Calendar' };
calendar.events = [
{ title: 'Identity', start: '2026-09-08', end: '2026-10-06', color: 'var(--ds-zenith-blue)' },
{ title: 'Website', start: '2026-10-02', end: '2026-11-13', color: 'var(--ds-apple-green)' },
{ title: 'Campaign', start: '2026-11-09', end: '2026-12-04', color: 'var(--ds-pink)' },
]; A contribution grid: weeks across a square each, the days down them as quiet squares, a day something happened on filled with its colour. Hover a day for its date.
<ds-calendar activity no-header></ds-calendar> const calendar = document.querySelector('ds-calendar');
calendar.events = [
{ title: 'Purchase', start: '2026-10-03', color: 'var(--ds-apple-green)' },
{ title: 'Purchase', start: '2026-10-08', color: 'var(--ds-yellow)' },
{ title: 'Purchase', start: '2026-10-21', color: 'var(--ds-pink)' },
]; A month
Section titled “A month”<ds-calendar month="2026-10" selectable week-numbers></ds-calendar>const calendar = document.querySelector("ds-calendar");calendar.events = [ { title: "Design review", start: "2026-10-03", time: "10:00", color: "var(--ds-zenith-blue)" }, { title: "Launch", start: "2026-10-12", end: "2026-10-14", color: "var(--ds-apple-green)" },];calendar.addEventListener("change", event => console.log(event.detail.value));| Measure | Size |
|---|---|
| A day | Four squares wide (day-width), its date’s square, lines squares of events (two), and one square to spare. |
| The title and arrows | One square, one square above the days. The title is a plain button, its words alone with no chevron, one control high, filled by the pointer 4px past its words at each side (see months and years). A step back, Today and a step on stand at the end as one plain split button: the segments a pixel apart, one control high, their words and arrows in the title grey on no ground in any state, inked by the pointer. A compact month keeps its chevrons, a square each. |
| The weekday names | Inside the first week’s boxes, at the start of each day’s first square, across from its date, in the title grey; today’s weekday in today’s red. A compact month keeps a row of their own over the days, a letter each. |
| A date | At the end of its first square, in the title grey, tabular figures. |
| Today | A disc nine tenths of a square across, in red for blood, the date in white. |
| The selected day | A square of the same size with the system’s 4px corners, in Sharp blue, the date in white. |
| A range | Each end drawn as the selected day, the days between on a band of the blue at 16%. In a compact month the band is the marks’ height on their line, from the middle of the first day to the middle of the last, so the ends and the band read as one bar. |
| An event | One square, drawn one pixel short, its words 4px from its edges; the time first, fainter. Filled with its color or the fill. |
| More events than lines | The last line says +2; pressing it lays the day’s events over the days below. |
| A week number | W42 in the compressed face, at the start of the week’s first day (after its name in the first week), with week-numbers; a week from Sunday takes its Monday’s number. |
| Lines | 1px in the line colour, centred on the grid lines. |
| The frame | Rounded on its four corner days at three times a card’s corner, at most a square: 12px on the base card, square where cards are. |
A day outside the month is an empty box. fixed always draws six weeks, so moving between months never changes the calendar’s height. With views, it also keeps every view at that height, so nothing under the calendar moves when a person changes the view: the week’s days grow to it, the day’s hours fill what its untimed events leave, the swimlane’s rows fill it under the months and dates and scroll past it, and a page’s own view gets it and scrolls inside.
The month’s title
Section titled “The month’s title”The title names the month and year (“October 2026”). Give monthHeading a function to write it in your own words: it is a property, given the first of the month shown as a Date and the view shown, and returns the title’s text; it names a page’s own view’s title too. The week, day and swimlane views, the twelve months and the twelve years keep their own titles, and the title stays the button that opens the months, its name saying so.
const calendar = document.querySelector("ds-calendar");calendar.monthHeading = month => `Events in ${month.toLocaleDateString("en", { month: "long" })}`;Compact
Section titled “Compact”compact makes every day a square, one square across by default: the date centred in it, the weekday names a letter each, the month’s name shortened, and no events written out. With day-width="2" each day is two squares each way, the weekday names take two letters, Today stands beside the arrows and the marks grow to a square and two thirds, for a month with more room. outside-days writes the days of the months before and after in the title grey; pressing one goes there. When the calendar has events, a day with one keeps the ink and a day without falls back to the title grey, so a year of small months shows where things happened.
Dragging the month or Swimlane horizontally reveals the adjacent page under the pointer on phones and computers. A trackpad follows its horizontal scroll before settling. Releasing settles or returns the page; vertical gestures keep page scrolling, cancelled gestures keep the selected dates, and reduced motion changes the month immediately. Custom views can supply neighboring content in slots named after the view, such as earnings-previous and earnings-next, alongside the current earnings slot. Prepare those months from the same authorized data before a gesture begins.
<ds-calendar compact heat fixed></ds-calendar>calendar.events = [ { title: "3 changes", start: "2026-07-08", count: 3 }, { title: "12 changes", start: "2026-07-09", count: 12 },];heat lights each day by how much happens on it, as a contribution graph does. A day’s amount is its events’ counts added up (an event without one counts once, an event over several days counts on each). The busiest day of the month shown sets the scale, and every other day takes one of four steps of it: up to a quarter, a half, three quarters, or more. heat-max fixes the amount that lights a day fully, so months stay comparable. A day with nothing stays plain, and when the month has events at all its date falls back to the title grey; the neighbouring months’ days are never lit.
| Step | Light paper | Dark paper | The date |
|---|---|---|---|
| 1 | The accent’s pastel | Its dim | The ink; white on dark paper |
| 2 | Halfway to the accent | Halfway to the accent’s dark version | The ink; white on dark paper |
| 3 | The accent (Apple green) | The accent’s dark version | The ink |
| 4 | The accent deepened with 40% of the ink | The full accent | The ink |
The fill is the date’s mark, the same size as today’s disc and the selected square, with a picture’s corners, so it stays inside the day’s square and the grid; in a compact month the marks stand a pixel apart, as a contribution graph’s squares do. Every step keeps its date at 4.5:1 or more. Today and the selection draw over the heat. The fills are the palette’s tokens (--one-apple-green-pastel, --one-apple-green), each light-dark(); a page lights the month in another colour by setting --ds-calendar-heat-1 … -4 and their --ds-calendar-heat-ink-1 … -4 from the palette.
Choosing a day or a range
Section titled “Choosing a day or a range”<ds-calendar compact selectable day-width="2" value="2026-10-14/2026-10-20"></ds-calendar>There is one way to choose, in a month and in the picker: a person picks one day or a range in the same calendar, with nothing to switch. The first press chooses a day, and value is that day. The next press ends a range from it, before or after, and value becomes start/end (ISO 8601’s interval); pressing the same day again keeps the one day. The press after that starts again. While the end is still to come, the day under the pointer previews it.
change fires with each press that chooses: { value, previous, start, end }, end empty while it is still to come and the last day once it is chosen. A value set by the page is whole, so the next press starts again.
A selectable calendar shows Clear while something is chosen: a secondary button one control high, in the shared word, centred on the square right under the dates. With nothing chosen it is not there. It empties the value and fires change with value empty (start and end too). clear() does the same from code, in a month and in a picker (where it also closes the panel). required leaves Clear out; the picker’s month uses the picker’s own Clear.
Months and years
Section titled “Months and years”Pressing the title travels by months and years, as a date picker’s title does. The days go up to the twelve months of their year (the title reads the year and the arrows step a year), the year goes up to twelve years (the title reads them, 2016 – 2027, and the arrows step twelve). Choosing a year shows its months; choosing a month shows its days and fires navigate. Nothing is chosen on the way.
| Measure | Size |
|---|---|
| A month or a year | One square high and whole squares wide, three across a narrow month (two squares each) and four across a wider one, rows one square apart. |
| Its mark | Hugs its words, as a button does: one control high on the row’s sixteen, padded 4px from the words, with a button’s corners, in the middle of its cell and never stretched across it. The current month or year and the chosen one take the accent (--ds-accent-color, lettered in --ds-button-text-color-on-accent), as a chosen segment does; the pointer’s takes the fill. |
| The title | A plain button hugging its words on every level, the pointer filling it only 4px past them; never a bar across the header. |
| The area | The days’ height, so nothing below moves between levels; the level a person moves to fades in (opacity and scale, none with reduced motion). |
The months and years are a grid with one Tab stop: the arrow keys move (past December is the next year’s January), Enter or Space chooses, and Escape goes back down a level without closing a picker. Month names and years come from the current language through format.ts. no-header leaves the travel out with the title.
Picker
Section titled “Picker”<form> <ds-calendar picker name="when" label="When" literal min="2026-10-01"></ds-calendar></form>picker.addEventListener("change", event => { console.log(event.detail.value); // "2026-10-21", "2026-10-21/2026-10-24", "2026-10-21T09:00/2026-10-21T10:00", or "" when cleared});With picker, the calendar is a field one control high, its value written in it and a chevron (chevron-down) at its end. A range is one picker and one value (Oct 21 – 24, 2026), never two pickers side by side for its ends. Pressing it opens a panel half a square below, on the menu’s frame: the first and last day written out where they can be typed, the compact month one square a day, an Include time switch and Clear.
It chooses as a month does. Each opening starts a new choice: the first day pressed is the value; the second, before or after, ends a range and closes the panel. Pressing the same day twice, or leaving after the first press, keeps one day.
The value is ISO 8601: a day, a day with its time, or two of them joined by a slash, which is also what a form sends. A value with a time turns Include time on; time sets it from the page.
| Value | Face |
|---|---|
2026-10-21 | Oct 21, 2026 |
2026-10-21/2026-10-24 | Oct 21 – 24, 2026 |
2026-10-21T09:00/2026-10-21T10:00 | Oct 21, 2026, 9:00 – 10:00 AM |
The face writes the value in the current language, a range as the language writes one. length writes a day short, medium (the default) or long; before a day is chosen the face reads placeholder, the shared words “Choose a date” by default, in the title grey.
| Measure | Size |
|---|---|
| The field | A field’s face: one control high at the foot of its square, as wide as its words (it hugs them, as a button does; --ds-calendar-picker-width sets a width), the words 4px in, the chevron-down icon (16px) 2px from the end. |
| The days to type | A field one control high on its own square for the first day and one for the last; with times on, each day’s time on the square below it. One square spare after them. |
| The month | One square a day, seven squares wide: the month with its chevrons, the weekdays in a letter, six weeks with the neighbouring months’ days in the title grey. |
| The marks | The chosen days are squares with 4px corners in Sharp blue, the days between on a band of it, today a red disc. |
| Include time, Clear | One square each, the switch at the end, set off by one-square separators with a line through them. |
| The frame | A 1px line with half a square inside it, no shadow: eight squares wide. |
| Its place | Half a square below the field, or above it when there is more room there, kept on screen. |
Turning times on gives the first day 9:00 and the last 10:00, which the time fields change; with times on, the panel stays open after the second press so they can be set.
A typed day is read when the person presses Enter or leaves the field: 2026-10-21, or a date the browser can read such as “Oct 21, 2026”. Anything else puts the field back as it was.
required leaves Clear out and tells the form a value is missing. min and max limit the days. A form’s reset puts back the value the field started with. readDateValue, writeDateValue and parseTypedDay are exported for a page that reads or writes the value itself.
Events
Section titled “Events”Both calendars take the same events, as a property:
| Field | What it is |
|---|---|
title | What happens. |
start | The first day, YYYY-MM-DD. |
end | The last day, for something over several days. |
time | When it starts, written before the title in a month. |
color | A token or colour for its fill. Take it from the palette. |
count | How much it counts for in heat; one when left out. |
id | Anything the page needs back; the calendar leaves it alone. |
A day lists its events longest first, then by time. An event over several days keeps one line through its week and is one bar, its name written once across the days; it breaks at the week’s end and where a day’s last line is given to “+N”. A name its bar cuts fades out over the bar’s last square, never with an ellipsis.
Week and day
Section titled “Week and day”view="week" shows the week date falls in (today’s by default), with every event of each day: the week is as many lines deep as its fullest day, and nothing folds behind “+N”. view="day" shows one day: its events without a time across the top, a day wide each, then its hours, one square each in an area twelve squares high that scrolls, each timed event at its hour beside the others of that hour; it opens an hour before the first one, or at seven. The arrows move a week or a day, Today goes to today’s, and the title still travels up to the months and years.
views puts Day, Week, Month and Swimlane on a split button in the middle of the header, which sets view and fires view-change with { view }. A compact calendar and a picker are always a month.
<ds-calendar views view="week"></ds-calendar>Choosing the views
Section titled “Choosing the views”Give views a list to offer only some views, in the order given: views="month swimlane". viewNames, a property, gives the words for each in the switch over the shared ones, so a page can call its month “Calendar”. A list with one view draws no switch. A view the calendar draws can still be set with view when it is not offered.
A name in the list that the calendar does not draw is the page’s own view. Chosen, the calendar keeps its header (the title from monthHeading, or the month’s, and the arrows moving a month, with navigate saying so) and shows what the page put in the slot of that name, as wide as the month, in place of the days. The page reads the month from shownMonth and draws its own content, such as a chart of the months, under the same header.
<ds-calendar views="month swimlane earnings"> <div slot="earnings">…</div></ds-calendar><script type="module"> const calendar = document.querySelector("ds-calendar"); calendar.viewNames = { month: "Calendar", earnings: "Earnings" };</script>Event fills round only their exposed start and end corners, using the system’s corner radius. Touching bars and vertically stacked events share square seams; staggered stacks keep only their free corners rounded. A continuation clipped by a week, hidden date or the visible timeline remains square, so it does not look like the event ends there. The rule is the same in a month and Swimlane, and follows the chosen square/rounded shape. The outer frame is painted above event fills, while internal day lines remain behind spanning bars; changing this layer does not move the grid or the events.
Swimlane
Section titled “Swimlane”Set swimlane-all to show every event in one timeline, scaling its columns by whole weeks to cover the full date range. Events without a valid start are shown separately as undated, named by undated-label; navigation is hidden in this view. Set swimlane-hug to fit the view to its visible event rows, with one empty row when there are none. It overrides the fixed height and internal scrolling for the swimlane only; the month and other views keep fixed.
view="swimlane" shows the events over weeks rather than days, for plans and projects that run for weeks or months. The weeks run across from the one holding the month’s first day, a square each (20 by 20), so the swimlane is as wide as the month and holds a week to each of its squares: 28 weeks, about six and a half months. Above them stand the months, each named where the month owning most of a week changes (with its year on the first and on January), and each week’s first date in the title grey; today’s week writes today’s date in its red disc instead. Each event has a row of its own, a square high, in the month’s hairline boxes and rounded frame, and is one bar from the week of its first day to the week of its last, filled with its color, its name on the sixteen, written once and fading where the bar cuts it. Rows run by first day, the longer first; there are always at least six, and one to spare under the last event. Pressing a bar fires event-press with the event and its first day. The arrows move a month and the title names the months shown (“Oct 2026 – Apr 2027”). With fixed, 23 rows fill the month’s height and more scroll.
<ds-calendar views view="swimlane"></ds-calendar>swimlaneBars(events, weeks), exported beside the calendar, gives the rows and weeks each event takes, for a page that draws its own legend or summary.
Days and weeks
Section titled “Days and weeks”A day is written YYYY-MM-DD and stays on its date in every time zone. The week starts where the language starts it (Monday in most of Europe, Sunday in the United States and Japan); week-start sets it, 0–6 from Sunday or a day’s English name. Month and weekday names come from the current language.
min and max limit the days a person may choose: the days outside them are drawn faint and cannot be selected. dayAllowed, a property taking a function from a day to true or false, leaves out more days between them, such as the days a booking has no room left. Set a new function when what it reads changes, and the days are drawn again. today draws another day as today, for a preview or a test.
calendar.dayAllowed = day => room.has(day);The day arithmetic the calendars use is DS1/0-face/calendar.ts, plain TypeScript without Lit: monthWeeks, addDays, addMonths, firstWeekday, weekdayNames, isoWeek, eventsByDay and the rest.
Accessibility
Section titled “Accessibility”- Each calendar is a grid named by its month (or
label), with one Tab stop on a day: the one moved to, the selected day, today, or the first. A selectable calendar isaria-multiselectable, and every day of the range isaria-selected. - A swipe sideways across the days or the months, by finger or pen, does what the arrows do: towards the start goes to the next month (year, twelve years), towards the end to the one before, and a trackpad’s sideways scroll the same, stopping where the arrows stop. The days take sideways touches for it (
touch-action: pan-y), so a carousel or a page around the calendar stays put while up and down still scroll. A calendar withno-headerdoes not swipe. - The arrow keys move a day, or a week across the weeks; Home and End go to the week’s first and last day; Page Up and Page Down move a month, with Shift a year. A month moves on when the focus leaves it, and right to left the arrows turn round.
- Enter or Space presses the day. Each day is labelled with its whole date and what happens on it, and today is
aria-current="date"; a selectable calendar marks the selected day witharia-selected. - The arrows are named “Previous month” and “Next month” (“Previous year”, “Next year”, “Earlier years” and “Later years” among the months and years), and the month’s name is announced when it changes. The title button is named by the title and “Choose a month and year”. All the words are the shared words, in every language.
- A picker’s field is a button with
aria-haspopup="dialog"andaria-expanded, named bylabeland the value. Enter, Space or the down arrow opens the panel with the focus on the first chosen day (or today); a click opens it and leaves the focus on the field. The typed fields and times are named by the label and which end they are; the switch isrole="switch". Escape, a press outside, or the focus leaving closes the panel, and the focus goes back to the field.
ds-calendar
Section titled “ds-calendar”| Attribute | Type | Default | What it does |
|---|---|---|---|
month | string | The value’s month, or today’s | The month shown, YYYY-MM. |
value | string | "" | The selected day or range; in a picker, with or without times. |
selectable | boolean | false | Pressing a day selects it, or ends a range. |
picker | boolean | false | A field that opens the small month. |
compact | boolean | false | One square per day. |
day-width | number | 4 (1 compact) | Squares per day. |
view | string | month | month, week, day or swimlane. |
views | boolean or list | false | Day, Week, Month and Swimlane in the header, or the views to offer, in order; a name it does not draw is the page’s own view, in the slot of that name. |
date | string | Today, or the month’s first | The day the week or day view shows. |
lines | number | 2 | Lines of events under a date. |
week-numbers | boolean | false | The week’s number on its first day. |
fixed | boolean | false | Always six weeks, and every view at that height. |
activity | boolean | false | Activity squares: weeks across, the days down them as quiet squares. |
months | number | 1 | How many months activity draws from month. |
outside-days | boolean | false | The days of the months before and after, in the title grey. |
heat | boolean | false | Light each day by how much happens on it. |
heat-max | number | The busiest day shown | The amount that lights a day fully. |
no-header | boolean | false | Leave out the title and arrows. |
no-today | boolean | false | Leave out the Today button. |
min, max | string | — | The days a person may choose. |
week-start | string | The language’s | The week’s first day. |
today | string | The reader’s today | The day drawn as today. |
label | string | The month (a picker: “Date”) | The grid’s or the picker’s name; literal shows it as written. |
name | string | — | The form field’s name. |
placeholder | string | “Choose a date” | A picker’s words before a day is chosen. |
length | string | medium | How a picker writes a day. |
time | boolean | false | A picker chooses a time with each day (Include time). |
required | boolean | false | A form needs a value; Clear is left out. |
disabled | boolean | false | A picker cannot be opened. |
open | boolean | false | A picker’s panel is open. |
Properties only: events, the days’ events; viewNames, Record<string, string>, the words for each view in the switch; monthHeading, (month: Date, view: string) => string, the month view’s title and a page’s own view’s (see the month’s title); and dayAllowed, (day: string) => boolean, the days that may be chosen between min and max (see days and weeks).
| Event | Detail | What it means |
|---|---|---|
day-press | { day, events } | A day was pressed, or chosen with Enter or Space. Cancel it to keep a selectable calendar’s value. |
change | { value, previous, start, end } | A person selected a day, or the end of a range. |
input | { value, previous, start, end } | A picker’s value changed, the same moment as change. |
ds-calendar-toggle | { open } | A picker’s panel opened or closed. |
event-press | { event, day } | An event was pressed (in a month). |
navigate | { month } | A person moved to another month. |
| Method | What it does |
|---|---|
previousMonth(), nextMonth() | Moves a month, as the arrows do. |
showToday() | Brings today’s month into view. |
showMonth(month) | Shows a month (ds-calendar). |
clear() | Empties the value, as Clear does, and fires change. |
show(), hide() | Opens or closes a picker’s panel. |
| Part | What it is |
|---|---|
header, title, previous, next, today | The title row and its buttons. |
picks, pick, foot, clear | The months or years, one of them (with selected and today), and Clear’s row and button. |
grid, weekdays | The grid and its weekday names. |
day, week, event, more | A month’s days, weeks, events and the +2 line; a day also carries today, selected and heat. |
swimlane, months, dates, scroll | A swimlane, its months and week dates over the weeks, and the rows that scroll past a fixed height. |
activity | Activity squares; their days are day (with today and filled) and their weekdays weekdays. |
own-view | Where a page’s own view is drawn, from its slot. |
trigger, popover, field, options, clear | A picker’s field, its panel, a row of a day or a time to type, and Include time and Clear. |
| Custom property | Default | What it sets |
|---|---|---|
--ds-calendar-today | var(--ds-red-for-blood) | Today’s disc. |
--ds-calendar-selected | var(--ds-sharp-blue) | The selected day and a range’s ends; the band between is it at 16%. |
--ds-calendar-event-radius | var(--ds-radius) | Exposed event corners; shared edges and continuations stay square. |
--ds-calendar-event-fill | The fill (Apple green on activity squares) | An event without a colour. |
--ds-calendar-line | 1px solid var(--ds-border-color) | A month’s lines. |
--ds-calendar-picker-width | Its words’ width | A picker’s field. |
--ds-calendar-heat-1 … -4 | The accent’s four steps | Heat’s fills. |
--ds-calendar-heat-ink-1 … -4 | The ink, or white on the dark steps | The date on each step. |
Activity squares
Section titled “Activity squares”activity draws the days as a contribution grid on the swimlane’s footing: a week to a column a square wide and the seven days down it, every other weekday named before them and the month over its weeks. Each day is a square drawn two pixels in with a picture’s corners, quiet in the fill, or filled with its events’ colours (split into bands when several share a day, Apple green for an event without a colour). Days outside the months are left empty. Dates and events stay in each day’s name and tooltip. month is the first month and months how many (one by default); use no-header for a fixed month.
<ds-calendar activity no-header month="2026-10"></ds-calendar>Set events as a property, as with a month. Days without events stay quiet; more events on one day do not deepen the colour (use heat for amounts). This replaces the large calendar’s months in squares, which is retired: a long piece of work over weeks is a swimlane.
select.hug- Select and date-picker triggers use hug sizing, never fill sizing or growing to occupy the available row.
On mobile, the picker’s small month centres on the field, 4 CSS pixels below it. It shifts inward at screen edges, opens above when that has more room, and scrolls within the visible keyboard viewport when necessary. Clear closes the picker and returns focus to the field. A standalone calendar used inside an app-owned context still emits its empty value; the app closes that context after saving it.