Skip to content

Editor (Pro)

The editor is a ready-made dialog for the Pro: a person opens an event, changes what they need, and saves. The change goes through the calendar’s own history, so it is checked against your rules and can be undone. It creates and edits; where the event is stored is still your decision, through your sources and store. This guide covers wiring it, what a person can do in it, and how it ends.

Terminal window
npm install @dzcalendar/pro @tzslot/dom

@tzslot/dom is an optional peer dependency of @dzcalendar/pro: install it with the editor, which uses its date and time-zone widget. The editor comes from its own entry, @dzcalendar/pro/editor; the Angular, React and Vue wrappers (@dzcalendar/pro-angular, -react, -vue) load it for you.

Two callbacks of the calendar lead to the editor: onEventOpen (“Open” in an event’s context menu, Enter or Space on a focused event, and a click in the list view) and onCreateRequest (“New event at 09:00”, or “New all-day event on…” in a month, in the menu of empty time). Giving the editor to the calendar means answering both with it — which also makes the context menu offer those entries.

import { createCalendar } from '@dzcalendar/dom';
import { editorHandlers } from '@dzcalendar/pro/editor';
const calendar = createCalendar(element, {
timeZone: 'Europe/Paris',
editable: true,
events: [{ id: 'a', title: 'Consultation', start: '2026-10-21T09:00[Europe/Paris]', duration: { minutes: 45 } }],
});
// "Open" and "New event here" now open the editor.
calendar.update(editorHandlers(calendar, { stepMinutes: 5, defaultMinutes: 30 }));

Things to know about the wiring:

  • The editor takes the two callbacks over. In Angular dzEventEditor makes (eventOpen) and (createRequest) stop firing; in React and Vue useEventEditor does the same for their props and events, until the component goes. To decide event by event, leave the wrapper out and call openEventEditor yourself from your own onEventOpen (see below).
  • A click is yours, outside the list. In the time grid, the month and the timeline, a click or tap on an event only calls onEventClick; the editor answers “Open”, Enter and Space. In the list view, a click on an entry opens it too. If you give onEventClick, Enter, Space and the list’s click go to it instead — decide there whether it should open the editor.
  • It reads editable. An event the person may not change opens read-only, by the same rule as the context menu: the calendar’s editable, and the event’s own editable, startEditable and durationEditable. The dialog says “Read only” under its heading (and to assistive tech, as its description), shows the fields without letting them change, and offers Close alone — no Save, no Delete. An event that may move but not change its length (or the reverse) opens editable with its times fixed: the title, colour, resources and repeat can change, the start, end and zone are shown disabled (a drag still does what is allowed). Creating is not an event’s to forbid: a calendar that is not editable still creates through the editor, as its menu still offers “New event here”.
  • One editor per calendar. Asking for a second while one is open gets the first, not a stack of dialogs.
  • Without a wrapper, editorHandlers(calendar, options) is the plain JavaScript way, as above. It needs the calendar, so it is given through calendar.update once the calendar exists; a later onEventOpen or onCreateRequest given to update replaces it.

The menu’s “New event at…” gives the editor a point: { allDay, start, resourceId? } from onCreateRequest, already snapped to snapMinutes. The editor fills the form from it: an hour long (defaultMinutes changes that) in the calendar’s time zone, or a whole day when the request was for a day, in the resource it was made on. Nothing is created until the person saves.

A selection is a range: hand its end over with its start (since 1.1). A timed end is a moment after the start (the selection’s ZonedDateTime, or an Instant); a whole-day end is the date after the last day, exclusive, as the selection gives it. Without an end, defaultMinutes (or one day) still applies. An end the editor cannot use — another kind, or not after the start — is left out and told as a warning through the editor’s onProblem option; it never throws. The selection stays drawn while the dialog is open: clear it when it closes.

import { Temporal } from '@dzcalendar/core';
import { createCalendar } from '@dzcalendar/dom';
import { openEventEditor } from '@dzcalendar/pro/editor';
const calendar = createCalendar(element, {
timeZone: 'Europe/Paris',
editable: true,
selectable: true,
snapMinutes: 30,
onSelect: (selection) => {
const { start, end, resourceId } = selection;
const where = resourceId === undefined ? {} : { resourceId };
let done: Promise<unknown> | null = null;
if (start instanceof Temporal.ZonedDateTime && end instanceof Temporal.ZonedDateTime) {
done = openEventEditor(calendar, { create: { allDay: false, start: start.toInstant(), end, ...where } });
} else if (start instanceof Temporal.PlainDate && end instanceof Temporal.PlainDate) {
done = openEventEditor(calendar, { create: { allDay: true, start, end, ...where } });
}
void (done ?? Promise.resolve()).then(() => calendar.select(null));
},
});

A selection across a clock change keeps its real length: its end is a moment, not a clock reading, so a night when Paris goes back to winter time opens with its extra hour. A whole-day selection opens across every day selected. The frameworks do the same from their onSelect handler, calling openEventEditor with the controller’s calendar, as in the Selection guide.

The dialog is one form, in the order of what people change most:

  • Title. It has the focus when the dialog opens.
  • When. A start and an end, each a date and a time, with a switch for whole days. The widget is tzslot’s date-and-time range: it shows the measured length, so a night across a clock change says its real hours. See Time zones.
  • Time zone. Each event keeps its own. The field edits the event’s wall clock: changing the zone keeps the moments, and shows them on the new zone’s clock. An event that ends in another zone than it starts (a flight, Paris to Tokyo) keeps both ends as they are unless the person changes the zone in the dialog.
  • Resources, when the calendar has resources: the rows or columns the event belongs to.
  • Colour, one of the tones (six by default; tones offers others).
  • Repeats, below.
  • Delete, for an event that already exists, when the person may delete it (as the context menu offers it).

Only what changed is sent. A title edited on an event that already overlaps another is not refused for its times, because its times were not touched. When nothing changed, saving writes nothing, so an occurrence is not turned into an override for no reason.

Before saving, the dialog checks what it can read: a start and an end; for a repeat, a whole interval and count of at least one, at least one weekday for a weekly rule, a last date that is not before the first. It says what is wrong in the dialog, marks the field with aria-invalid and moves the focus to it.

The repeat is the usual set: does not repeat; every N days; every N weeks on chosen weekdays; every N months, on the day, on the n-th weekday (“the third Wednesday”) or on the last one; every N years. It ends never, on a date (that whole day included), or after N times. The week starts as the calendar’s does (its locale, or firstDay).

A rule beyond that — hours, set positions, several rules — is shown as written, under “Custom rule”, and is kept exactly as it is unless the person picks another repeat. A rule written another way (its own week start, its weekdays in another order) is compared as a form, not as text, so saving a title never rewrites it. The rules themselves are in the Recurrence guide.

An occurrence of a series opens with the question of how far the edit reaches, in the calendar’s own words:

The person picks The edit reaches
This event That occurrence only, kept as an exception of the series
This and following events That occurrence and the ones after it (the series is split there)
All events The series, every occurrence

chooseScope is the same question for drags and the Delete key; the editor asks it in the form instead, because the person is already looking at it.

The repeat itself belongs to the series, so it shows only with “All events”, and “This and following” with another rule is not offered. With “All events”, another rule is given to the series, which keeps its excluded dates and moved occurrences and its own week start; when the series is moved in the same save, the rule moves with it (a Wednesday rule moved to Thursday repeats on Thursdays). Choosing “does not repeat” stops the series: its first occurrence becomes an ordinary event with the same id and every field kept, and the occurrences that were moved stand alone. A single event made to repeat keeps its id and its fields.

A promise tells you how the dialog ended. openEventEditor(calendar, target) resolves, onClosed and (editorClosed) receive it, with one of three outcomes:

  • 'saved', after the change was applied;
  • 'deleted', after the Delete button (on an occurrence it deletes what the scope says);
  • 'cancelled', for Cancel, Escape, a click outside an untouched form, the calendar being destroyed, or the editor’s chunk failing to load.

A saved change is an ordinary command in the calendar’s history: Ctrl/Cmd+Z undoes it (see keyboardUndo), as does calendar.undo(); a save that touched an event and its series at once is undone as one step. Here the application confirms the save with a way back:

import { createCalendar } from '@dzcalendar/dom';
import { openEventEditor } from '@dzcalendar/pro/editor';
declare function showToast(text: string, undo?: () => void): void;
const calendar = createCalendar(element, {
timeZone: 'Europe/Paris',
editable: true,
onEventOpen: async (instance) => {
const outcome = await openEventEditor(calendar, { instance });
if (outcome === 'saved') showToast('Saved', () => calendar.undo());
if (outcome === 'deleted') showToast('Deleted', () => calendar.undo());
},
});

Delete asks nothing more: it deletes at once, as far as the “Apply to” choice reaches on an occurrence (“This event” unless the person picked another), and the way back is undo, as above.

A click outside the dialog cancels only a form nobody touched, so a stray click does not lose what was typed. The focus goes back to where it came from: the event (also when the dialog was opened from its context menu), or, for a new event from the menu, the calendar’s focused day or slot. If the calendar is destroyed while the editor is open, the editor closes with it.

A change is saved with the calendar’s rules on: a constraint, an overlap, a resource’s own rules, allow. When one refuses, the dialog stays open and says why in a role="alert" line, in the calendar’s words for that refusal, so the person can fix the time and save again. A series is checked on its occurrences, not only its first: a daily rule that lands on a booked day is refused, the check looking at a year of occurrences, 500 at most. Input the dialog cannot make sense of is said in words too, never thrown.

The refusal is the same one a drag would meet; see Drag and drop for the rules and how they say no. Your server can still refuse after the editor: see Events for saving what a person changed.

The editor speaks the calendar’s locale: English, French, Arabic, Spanish and German are built in, from editorMessagesFor. Its scope words and the reasons it gives for a refusal are the calendar’s words: the locale’s, with the calendar’s messages laid over them, as the calendar itself speaks (the form’s words are the editor’s). Change the editor’s own words with its messages option; add a language with defineEditorLocale, which takes a complete set — start from EDITOR_EN:

import { createCalendar } from '@dzcalendar/dom';
import { EDITOR_EN, defineEditorLocale, editorHandlers } from '@dzcalendar/pro/editor';
defineEditorLocale('nl', { ...EDITOR_EN, newEvent: 'Nieuwe afspraak', editEvent: 'Afspraak wijzigen', save: 'Opslaan', cancel: 'Annuleren', remove: 'Verwijderen' });
const calendar = createCalendar(element, { timeZone: 'Europe/Amsterdam', locale: 'nl' });
calendar.update(editorHandlers(calendar, { messages: { save: 'Book it' }, tones: ['blue', 'green', 'red'] }));

tzslot’s own widget has its words in English, French and Arabic: under Spanish, German or a language of yours, its few labels (the length, “all day”) stay in English until it has them.

Look. The dialog reads the calendar’s palette — the page’s --tz-* tokens first, as the calendar does — and hands it on to tzslot’s widget and its pickers, so a theme reaches the editor with no extra work. It is appended to the calendar’s element (container puts it elsewhere) and its styles follow the calendar’s: layered as cssLayers decided, and unstyled under look: 'none'. Under a strict Content Security Policy, give injectStyles: false to the editor and include EDITOR_CSS in your own stylesheet, as the calendar’s own injectStyles asks for its sheets.

The dialog is a role="dialog" with aria-modal, named by its heading. Tab stays inside it, Escape cancels (while one of the date pickers is open, Escape closes the picker first), and the dialog opens with the calendar’s motion: a short fade by default; with @dzcalendar/motion-gsap it grows out of the event and closes back into it. Under prefers-reduced-motion, it simply appears and goes. The keys of the grid are in Keyboard and accessibility.

The editor is not part of the calendar’s first load. The Angular, React and Vue wrappers fetch it, with tzslot’s widget, on the first opening, not with the application; if that fetch fails, the outcome is 'cancelled' and the error is reported. In plain JavaScript, do the same with a dynamic import:

import { createCalendar } from '@dzcalendar/dom';
const calendar = createCalendar(element, {
timeZone: 'Europe/Paris',
editable: true,
onEventOpen: (instance) => void import('@dzcalendar/pro/editor').then((m) => m.openEventEditor(calendar, { instance })),
onCreateRequest: (request) => void import('@dzcalendar/pro/editor').then((m) => m.openEventEditor(calendar, { create: request })),
});

What it weighs, in round numbers: about 11 kB gzipped for the editor itself, and about 38 kB with tzslot’s widget — that is what the first opening costs, on top of the calendar. It also brings the recurrence entry (@dzcalendar/core/recurrence, about 16 kB), unless your calendar already loads it for its repeating events. The widget comes without the Temporal polyfill; the application loads that only where the browser lacks Temporal, so it is not in the editor’s chunk.