Calendar API Reference

API reference › The calendar viewer

All 21 pages Everything on one page → Developer guide →

The calendar viewer

modules/calendar is an opt-in view of grid rows as cards on a month grid or a week day-grid, keyed by a date field. It is a separate bundle in the same shape as charts, kanban and the data router: it adds no weight to a page that does not load it, changes nothing in grid core, and pulls in no dependency. A calendar is just another dataset viewer: it consumes data through the same keyed-diff contract a grid exposes, calendar.rows.apply({ add, update, remove }) (plus rows.get(key)), so a Data Router can attach(value, calendar) and drive a calendar beside a grid, a kanban and a chart off one feed.

import { createCalendar } from '@toclocoinc/lattice-grid/modules/calendar';

const calendar = createCalendar(document.querySelector('#calendar'), {
  rows,                          // or { grid } to bind a live grid
  rowKey: 'id',
  startProperty: 'posttime',     // the point-event start (configurable)
  view: 'week',                  // 'week' | 'month'
  header: { navigation: true, title: true, views: true },
  card: { title: 'name' },
  colorProperty: 'status',       // colour the card edge by a property
  onCardClick: ({ row }) => open(row),
});

The date field is startProperty (default 'start'); an optional endProperty turns point events into multi-day spans, drawn as one continuous bar across the days they cover. Days grow with their cards (--lattice-calendar-cell-min-height, default 120px; the page scrolls, never the calendar), and the built-in header (or header: false) carries prev / next / today, the title (SEP 28 - OCT 4, 2026 for a week, SEPTEMBER 2026 for a month, via Intl.DateTimeFormat(locale)) and a week/month toggle, styled only through theme tokens. The week-time and day views add a vertical hour axis: a row with a start time is a block positioned at its start and sized by its end (defaultDuration when there is none), overlapping blocks split the column side by side, all-day rows stack in a top all-day row, businessHours shades the working span, and a now line marks the current time in the current day column. slotDuration (default 30 minutes), slotMinTime/slotMaxTime, scrollTime and weekNumbers tune the axis, and times read through the grid's timeZone rule (a 12:17Z post shows 13:17 under Europe/London summer time). A row whose start is empty or unparsable is counted in unscheduled and reported once, never thrown. Accessibility is built in: role="grid" with columnheader/gridcell, a roving-tabindex focus ring across cards, arrows by day/week (and by slot in the time grid), PageUp/PageDown by period, a live region announcing the range and card count, and an announced time slot on each timed block.

Week and month, navigation and state, executed

Point events on a week grid, one unparsable start counted in unscheduled, the de-dup contract (add of an existing key is an update), navigation firing range:change, and the versioned state round-trip. Run headless on every build.

const { createCalendar } = await import('../packages/modules/calendar/index.js');
const cal = createCalendar(null, {
  rows: [
    { id: 'a', start: '2026-09-28 10:00', title: 'Login' },
    { id: 'b', start: '2026-09-28 14:00', title: 'OAuth' },
    { id: 'c', start: '2026-10-02 09:00', title: 'Reset' },
    { id: 'd', start: '', title: 'No date' },
  ],
  rowKey: 'id', startProperty: 'start', view: 'week', date: '2026-09-30', firstDay: 1, locale: 'en-GB',
  header: { navigation: true, title: true, views: true },
  card: { title: 'title', subtitle: 'subtitle' },
  ariaLabel: 'Calendar', labels: { today: 'Today', week: 'Week', month: 'Month' },
  readonly: false, timeZone: 'Europe/London',
});
const heard = [];
cal.on('range:change', (e) => heard.push(e.view));
const off = () => {};
cal.on('range:change', off); cal.off('range:change', off);
const count = cal.rows.count;                       // 4
const unscheduled = cal.unscheduled.length;         // 1
const startDay = cal.getRange().start.getDate();    // 28
const endDay = cal.getRange().end.getDate();        // 4
cal.rows.apply({ add: [{ id: 'a', start: '2026-09-28 11:00', title: 'Login v2' }] });
const dedup = cal.rows.count;                       // 4
const title = cal.rows.get('a').title;              // Login v2
cal.next(); cal.prev(); cal.today();                // range:change x3
const changes = heard.length;                       // 3
cal.goTo('2026-09-30');
const nextRange = cal.getRange().start.getDate();   // 28
cal.setView('month');
const monthDays = cal.model.days.length;            // 35
cal.refresh();
cal.rebind(null);                                   // no-op: this calendar is not grid-bound
const state = cal.getState();                       // view month
cal.setState({ view: 'week', date: '2026-09-30' });
const restored = cal.getRange().view;               // week
const ro = cal.readonly({ day: '2026-09-30' });     // false
cal.destroy();
return [count, unscheduled, startDay, endDay, dedup, title, changes, nextRange, monthDays, state.view, restored, ro].join('|');

Spans, colour, overflow and the host renderer, executed

A multi-day span (one continuous bar, marked continuing), colour by property through a map, order by a field, the +N more overflow threshold, and a host renderer. Run headless on every build.

const { createCalendar } = await import('../packages/modules/calendar/index.js');
const cal = createCalendar(null, {
  rows: [
    { id: 's1', start: '2026-09-28', end: '2026-09-30', title: 'Span' },
    { id: 'p1', start: '2026-09-29 09:00', title: 'B', status: 'posted', rank: 2 },
    { id: 'p2', start: '2026-09-29 08:00', title: 'A', status: 'draft', rank: 1 },
    { id: 'p3', start: '2026-09-29 10:00', title: 'C', status: 'posted', rank: 3 },
  ],
  rowKey: 'id', startProperty: 'start', endProperty: 'end', allDayProperty: 'allDay',
  view: 'week', date: '2026-09-30', firstDay: 1,
  colorProperty: 'status', colorMap: { posted: '#16a34a', draft: '#6b7280' },
  eventOrder: 'rank', dayMaxEvents: 2,
  renderCard: (row, el) => { el.textContent = row.title; },
  onCardClick: () => {}, onCardDblClick: () => {}, onCardContextMenu: () => {}, onRangeChange: () => {},
});
const spanBars = cal.model.days.find((d) => d.key === '2026-09-28').spans;
const span = spanBars[0];
const continuing = span.span;                        // true
const clippedBefore = span.continuesBefore;          // false (starts in range)
const sep29 = cal.model.days.find((d) => d.key === '2026-09-29').cards;
const order = sep29.map((c) => c.row.title).join(',');   // A,B,C (by rank)
const colour = sep29.find((c) => c.row.id === 'p1').color; // #16a34a
cal.destroy();
return [continuing, clippedBefore, order, colour].join('|');

The hour axis, overlap columns, all-day and the now line, executed

The week-time/day time grid: a timed block positioned by its start and sized by its end, overlapping blocks splitting the column, an all-day row, business-hours shading, week numbers and the time-axis tuning keys. Run headless on every build.

const { createCalendar } = await import('../packages/modules/calendar/index.js');
const cal = createCalendar(null, {
  rows: [
    { id: 'a', start: '2026-09-30 09:00', end: '2026-09-30 10:30', title: 'Review' },
    { id: 'b', start: '2026-09-30 09:30', title: 'Overlap' },
    { id: 'all', start: '2026-09-30', title: 'All day' },
  ],
  rowKey: 'id', startProperty: 'start', endProperty: 'end', allDayProperty: 'allDay',
  view: 'day', date: '2026-09-30',
  slotDuration: 30, slotMinTime: '08:00', slotMaxTime: '18:00', scrollTime: '09:00',
  defaultDuration: 60, businessHours: { startTime: '09:00', endTime: '17:00', daysOfWeek: [3] },
  weekNumbers: true,
});
const day = cal.model.days[0];
const a = day.timed.find((b) => b.key === 'a');
const startMin = a.startMin;                         // 540 (09:00)
const endMin = a.endMin;                             // 630 (10:30)
const cols = a.cols;                                 // 2 (overlaps with b)
const allDay = day.allDay.length;                    // 1 (the date-only row)
cal.destroy();
return [startMin, endMin, cols, allDay].join('|');

Rescheduling, veto and write-back, executed

A move shifts the end by the same delta (duration kept); a resize changes the end only; a beforeMove veto cancels synchronously or by promise; card:move fires on success with the old and new values; and a standalone onCardMove returning false reverts. Run headless on every build.

const { createCalendar } = await import('../packages/modules/calendar/index.js');
const cal = createCalendar(null, {
  rows: [{ id: 1, start: '2026-09-28 10:00', end: '2026-09-28 11:00', title: 'A' }],
  rowKey: 'id', startProperty: 'start', endProperty: 'end', view: 'week', date: '2026-09-30',
});
await cal.move(1, { start: new Date(2026, 8, 29, 10, 0) });
const movedStart = cal.rows.get(1).start;             // 2026-09-29 10:00
const movedEnd = cal.rows.get(1).end;                 // 2026-09-29 11:00 (duration kept)
await cal.move(1, { end: new Date(2026, 8, 29, 12, 0) });
const resizedEnd = cal.rows.get(1).end;               // 2026-09-29 12:00 (end only)
const heard = [];
cal.on('card:move', (e) => heard.push([e.from.start.getDate(), e.to.start.getDate()]));
const veto = (e) => e.preventDefault('blocked');
cal.on('beforeMove', veto);
await cal.move(1, { start: new Date(2026, 8, 30, 10, 0) });   // vetoed: no card:move
const stayed = cal.rows.get(1).start;                 // 2026-09-29 10:00
cal.off('beforeMove', veto);
await cal.move(1, { start: new Date(2026, 8, 30, 10, 0) });
const firedFrom = heard[0][0];                        // 29
const firedTo = heard[0][1];                          // 30
cal.destroy();
const cal2 = createCalendar(null, {
  rows: [{ id: 1, start: '2026-09-28 10:00', title: 'B' }],
  rowKey: 'id', startProperty: 'start', view: 'week', date: '2026-09-30',
  onCardMove: () => false,
});
await cal2.move(1, { start: new Date(2026, 8, 29, 10, 0) });
const reverted = cal2.rows.get(1).start;              // 2026-09-28 10:00 (onCardMove reverted)
cal2.destroy();
return [movedStart, movedEnd, resizedEnd, stayed, firedFrom, firedTo, reverted].join('|');

Type reference

Generated from the type declarations, so it always matches the release. Each surface lists its properties, its methods and the events it raises as three tables; an option or value type lists its members once.

The calendar module

CalendarHeader

The built-in header toolbar. Each section is shown unless its flag is `false`; `header: false` (the whole object) renders no header at all and the host draws its own.

CalendarCardMap

The field-to-property mapping that drives the default card template.

CalendarPointerEvent

The payload of the three card pointer events - `card:click`, `card:dblclick` and `card:contextmenu`.

CalendarMountEvent

The payload of `card:mount` - the card's element was created and attached.

CalendarRangeEvent

The payload of `range:change` - the visible range moved.

CalendarMoveSpan

A card's start/end before or after a reschedule; either may be null.

CalendarMoveEvent

The payload of `beforeMove` and `card:move` - a card was (or may be) rescheduled.

CalendarConfig

The configuration for {@link createCalendar}. The data source is `rows` (an array) or `grid` (a live grid to bind). The date field is `startProperty`; an `endProperty` turns point events into multi-day spans.

CalendarRows

The keyed-diff consumer surface a calendar shares with a grid, so a Data Router routes to it directly.

Calendar

A calendar instance: a view of grid rows as cards on a month grid or a week day-grid. It consumes data through the same keyed-diff `rows.apply` contract a grid exposes, so `dataRouter.attach(value, calendar)` drives it like any other viewer.

Properties

Methods

Events

CalendarEventPayloads

What a handler receives, per calendar event.