Skip to content

Events

An event is plain data: an id, a title, a start with its zone, a length. You hand the calendar a list; afterwards every change — yours, a person’s drag, an undo — is a command, plain data too, that the calendar applies, records and can take back.

Pass them in events. A start is an ISO 8601 string or a Temporal value; a timed one names its zone, an all-day one is a date:

import { createCalendar } from '@dzcalendar/dom';
createCalendar(element, {
timeZone: 'Europe/Paris',
events: [
{ id: 'a', title: 'Consultation', start: '2026-10-21T09:00[Europe/Paris]', duration: { minutes: 45 } },
// Its own zone: 10:00 in Chicago, drawn at 17:00 in Paris.
{ id: 'b', title: 'Call Chicago', start: '2026-10-22T10:00[America/Chicago]', end: '2026-10-22T11:00[America/Chicago]' },
{ id: 'c', title: 'Day off', start: '2026-10-23', allDay: true },
{ id: 'd', title: 'Congress', start: '2026-10-26', end: '2026-10-29', allDay: true, tone: 'violet' },
],
});

What to know about those fields — every one is in the table of events:

  • Every event keeps its own zone. The call above is 10:00 in Chicago; the calendar, drawn in Paris, puts it at 17:00, and keeps it at 10:00 in Chicago if the calendar’s zone changes. A start written without a zone ('2026-10-21T09:00') is read in the calendar’s zone, and said as a guess.
  • end or duration. In a duration, days are days on the wall and hours are hours that pass: { days: 1 } from 09:00 ends at 09:00 the next day even over a clock change, { hours: 24 } at 08:00 or 10:00.
  • An all-day end is exclusive: the congress above covers the 26th, 27th and 28th.
  • Give every event an id. It is what keeps an event the same through a move, an undo, a new list.
  • A colour is a tone (tone: 'violet'), a name the theme draws, not a hex value — so it follows the light and the dark scheme. Your own data goes in extendedProps, read back as event.props.

To show another list, give the whole new one: calendar.update({ events }) — or, in a framework, a new array to the same input. The calendar compares it with the one it holds, by id and by value: an event that did not change is not drawn again, and the same list again changes nothing. A new array each time is fine. In a framework, an array changed in place and given back is the same array — not seen; calendar.update reads the array it is given again.

For events that come from a server as the person moves through the weeks, use a source instead: Event sources.

Each change is a command, given to calendar.run(…):

import { createCalendar } from '@dzcalendar/dom';
const calendar = createCalendar(element, { timeZone: 'Europe/Paris' });
calendar.run({ type: 'event.create', event: { id: 'x', title: 'Visit', start: '2026-10-21T14:00[Europe/Paris]', duration: { hours: 1 } } });
// Its length kept.
calendar.run({ type: 'event.move', id: 'x', start: '2026-10-22T15:00[Europe/Paris]' });
calendar.run({ type: 'event.resize', id: 'x', edge: 'end', to: '2026-10-22T16:30[Europe/Paris]' });
calendar.run({ type: 'event.update', id: 'x', patch: { title: 'Home visit', tone: 'green' } });
const result = calendar.run({ type: 'event.delete', id: 'nope' });
if (!result.ok) console.warn(result.problems); // [{ code: 'unknown-event', … }] — nothing thrown, nothing changed
Command Does
event.create Adds event (with an rrule, a series)
event.move A new start, the length kept unless end is given; resourceIds to change its resources
event.resize One edge ('start' or 'end') to a new moment, the other kept
event.update Lays patch over the event; null clears end, tone, url or groupId
event.delete Removes it
batch Several commands as one, undone as one

A series has its own commands, and its occurrences take a scope — see Recurrence.

A command never throws. It returns { ok: true, … }, or { ok: false, problems } with nothing changed: an unknown id, a start that cannot be read — or, from a framework’s controller, a calendar not drawn yet (not-mounted). Your own run is not checked against the rules (rules, editable): those are for a person’s gestures, and your code is trusted. Pass { validate: true } to have it checked as a gesture would be. Commands are plain data, so they can be logged, sent to a server or written by an assistant — @dzcalendar/core/commands.schema.json describes them as JSON Schema.

Every command run through the calendar — a person’s or yours — goes into its history. calendar.undo() and calendar.redo() take it back and put it again (both return false when there is nothing to do — an entry is also dropped when a source delivers a new version of the events it touched); Ctrl+Z and Ctrl+Shift+Z (or Ctrl+Y) do the same from the keyboard in an editable calendar (keyboardUndo). A drag is one entry however many times it moved, and a batch is one entry. The history keeps 200 entries (historyLimit).

In the frameworks the controller has undo(), redo() and canUndo, canRedo to draw your own buttons (a signal in Angular, useCalendarState in React, a ref in Vue).

Try it: move or resize the events, then press Ctrl+Z (⌘+Z on a Mac).

A person’s drag, resize, key, menu entry or editor ends in a command too. To write it to your server, listen to onEventChange. It receives one change at a time:

  • changes — every event and series it touched, each { kind, before, after } (kind is 'event' or 'series'; before is null for one created, after for one deleted). This is what to save: changing “all” the occurrences of a series, or deleting one, touches the series and no single event.
  • before and after — the first event it touched, as it was and as it is: enough for a calendar without series.
  • command — what was asked; cause — 'command', 'undo' or 'redo': an undo is a change to save too.

If your server refuses, call change.revert(): exactly that change is taken back, even when others came after it. It returns false, changing nothing, when those events have been changed again since, or for one step of a merged gesture or a transaction.

import { eventInput, seriesInput } from '@dzcalendar/core';
import { createCalendar } from '@dzcalendar/dom';
import type { EventChange } from '@dzcalendar/dom';
// Each event or series touched, as your server stores it: null when deleted.
const toWire = (change: EventChange) =>
change.changes.map((c) => ({
kind: c.kind,
id: (c.after ?? c.before)!.id,
data: c.kind === 'event' ? c.after && eventInput(c.after) : c.after && seriesInput(c.after),
}));
createCalendar(element, {
timeZone: 'Europe/Paris',
editable: true,
onEventChange: async (change) => {
const res = await fetch('/api/changes', { method: 'POST', body: JSON.stringify({ cause: change.cause, changes: toWire(change) }) });
if (!res.ok) change.revert();
},
});

What onEventChange is told, and what not:

  • A person’s change, to any event — a source’s events included.
  • Not your own calendar.run(): you know what you ran — unless you pass { validate: true }, which runs it as a gesture and tells it here.
  • But every undo and redo is told, calendar.undo() too, even of a command you ran yourself (cause: 'undo', no command). If you save from here, run your own commands with { validate: true } too, so that the server has seen what an undo takes back.
  • Not what a source delivers. A source with a save function also writes a person’s changes to its events — save them in one place: see Event sources.
  • Not a drop: an event dropped from the page or from another calendar is said once, to onEventReceive.
  • Not a refusal: a change the rules refused never happened; it is said by onCommandRefused or onProposalRefused.

Who may change what is decided by editable and each event’s own editable, startEditable and durationEditable.

Bad data never throws. An event without a start, with an unknown zone or an end before its start is left out, and the rest is shown. Ask what was left out:

const report = calendar.kernel.getProblems();
for (const p of report?.problems ?? []) console.warn(p.severity, p.code, p.path, p.detail);
// error unknown-zone … Europe/Pariss
// warning zone-defaulted … — taken, read in the calendar's zone

Each problem has a code (missing-start, unknown-zone, end-before-start, duplicate-id…), a severity ('error' left out, 'warning' taken, but guessed or adjusted), a path to the field and a detail. A source’s problems come through onSource instead. In the frameworks, the report of the events input is said by Angular’s (problems), React’s onProblems and Vue’s @problems; the controller’s problems holds the last report, of the events or of a source.