Drag and drop
Once a calendar is editable, a person drags an
event to another time or day, pulls its edge to make it longer or shorter,
and can undo it. Nothing changes while the pointer moves: a preview follows
it, and only the drop becomes a command — checked against your rules,
recorded in the history, and told to you once.
A mouse, a pen, a finger and the keyboard (see Keyboard and accessibility) all end in the same proposal: the rules, the questions and the callbacks below are the same for the four.
Let people move and resize
Section titled “Let people move and resize”Switch editable on. A timed event then drags to another time or day and
is pulled from its bottom edge; an all-day event drags between days and
stretches over more. In the month, every event moves by whole days, but
only an all-day one is resized there — a timed one keeps its hours.
Three settings shape the gesture:
snapMinutesis the step a time grid lands on, whatever the grid’s lines: an hourly grid can snap to five minutes.eventResizableFromStartlets a person pull the start of an event too, not only its end.- An event’s own
editable,startEditableordurationEditablewins over the calendar’s: one event can be fixed in an editable calendar, or only resizable. Seeeditable.
import { createCalendar } from '@dzcalendar/dom';
createCalendar(element, { timeZone: 'Europe/Paris', initialView: 'timeGridWeek', editable: true, snapMinutes: 5, eventResizableFromStart: true,});import { Component } from '@angular/core';import { DZ_CALENDAR } from '@dzcalendar/angular';
@Component({ selector: 'app-agenda', imports: [DZ_CALENDAR], template: `<dz-calendar timeZone="Europe/Paris" view="timeGridWeek" [editable]="true" [options]="{ snapMinutes: 5, eventResizableFromStart: true }" />`,})export class Agenda {}import { DzCalendar } from '@dzcalendar/react';
export function Agenda() { return <DzCalendar timeZone="Europe/Paris" defaultView="timeGridWeek" editable snapMinutes={5} eventResizableFromStart />;}<script setup lang="ts">import { DzCalendar } from '@dzcalendar/vue';</script>
<template> <DzCalendar time-zone="Europe/Paris" view="timeGridWeek" editable :options="{ snapMinutes: 5, eventResizableFromStart: true }" /></template>Try it: drag an event, then pull its top or its bottom. The preview shows the time it will land on, in steps of five minutes. Paris puts its clocks back on Sunday 25: drop an event between 02:00 and 03:00 that night and the calendar asks which 02:00.
What a drop keeps
Section titled “What a drop keeps”A timed event keeps its own zone and its elapsed length: “Call Chicago” stays a Chicago event wherever it lands, and one hour stays one hour across a clock change. The start is snapped on the wall clock of the calendar’s zone, then read again in the event’s.
- Dropped in an hour that does not exist (the clocks went forward), the event is pushed forward by the skipped time — 02:30 becomes 03:30 — and the calendar says so.
- Dropped at a wall time that happens twice (the clocks went back), the calendar asks which one — “First 02:00 (+02:00)” or “Second 02:00 (+01:00)” — before it changes anything. Close the question and the event stays where it was.
- Dragged onto the all-day row of a week, a timed event becomes an all-day one; dropped in the time grid, an all-day event becomes timed, with a default length. The change of kind is announced too.
- In a resource view, dropping on another resource moves the event there; an event on two resources keeps the other one.
Time zones explains the days of 23 and 25 hours these rules are made for.
Change period without dropping
Section titled “Change period without dropping”While an event is dragged, the grid scrolls when the pointer nears its top or bottom edge, and holding the pointer against the left or right side of the calendar goes to the previous or next period — after 0.6 s in a time grid, 0.9 s in a month or a timeline. The drag goes on in the new period: an appointment travels to next Tuesday in one gesture. A timeline first scrolls along time, and changes period only at the end.
Only a move pages; a resize, or an element dragged in from the page,
stays in the period shown. Set
dragEdgeNavigate to false to keep
every drag in its period.
With a finger
Section titled “With a finger”Dragging an event needs no long press (that opens its menu). A tap selects it — an outline and larger handles — and a drag on the selected event starts at once; on empty time or on an event that is not selected, the finger scrolls the page as usual. The event stays selected where it lands, ready for the next move.
An element dragged in from the page is not in a scrolling grid: there, the finger holds still for 300 ms first.
Refusing a drop
Section titled “Refusing a drop”A move or a resize is checked as the pointer travels. The preview turns red where the event may not land; let go there and the event goes back, the calendar announces “Not allowed here”, and nothing is recorded.
What refuses is declared in rules:
| Rule | Refuses |
|---|---|
constraint |
Leaving business hours, a group’s events, or spans you give |
overlap |
An event over another (false), or pair by pair with a function |
allow |
Whatever your function says no to |
validRange |
Days outside a range |
What a person does is checked — a gesture, the keyboard, the menu. A
calendar.run(command) of yours is not, unless you ask:
calendar.run(command, { validate: true }).
The calendar says that a drop was refused, not why in your words. Two callbacks let you say it:
onProposalRefusedhears a drag, a resize, a keyboard move or a drop from the page let go where the rules say no. Its proposal carries theviolations, each with itscode.onCommandRefusedhears a command refused although nothing was drawn refused: the Delete key, a menu entry, the scope chosen for a repeating event.
import { createCalendar } from '@dzcalendar/dom';
createCalendar(element, { timeZone: 'Europe/Paris', editable: true, businessHours: true, rules: { constraint: 'businessHours', overlap: false }, onProposalRefused: (proposal) => { const codes = proposal.violations.map((v) => v.code); if (codes.includes('constraint')) alert('Outside opening hours'); else if (codes.includes('overlap')) alert('Already something at that time'); }, onCommandRefused: (result, command) => console.warn(command.type, 'refused', result.problems),});In React, rules and both callbacks are props; in Angular and Vue they go in options.
Drag an event outside the hours, or onto another one:
Hear what changed
Section titled “Hear what changed”A drop that is made reaches onEventChange
once, whichever way it came — drag, resize, keyboard, menu, undo. Persist it
there, and take it back if your server says no: change.revert() undoes
that change, not “the last one” (it returns false, doing nothing, if those
events changed again since). Events goes further into saving.
import { createCalendar } from '@dzcalendar/dom';
createCalendar(element, { timeZone: 'Europe/Paris', editable: true, onEventChange: async (change) => { if (!change.after) return; const res = await fetch(`/api/events/${change.after.id}`, { method: 'PUT', body: JSON.stringify({ start: change.after.start.toString(), end: change.after.end.toString() }), }); // The server said no: the event goes back where it was. if (!res.ok) change.revert(); },});In the frameworks it is an output: Angular’s (eventChange), React’s onEventChange, Vue’s @event-change.
Every drop is one step of the history. With the focus in the calendar,
Ctrl/Cmd+Z undoes it and Ctrl/Cmd+Shift+Z or Ctrl/Cmd+Y redoes it;
keyboardUndo: false leaves those keys to
your application, and calendar.undo() / calendar.redo() work either way.
An undo reaches onEventChange too, with cause: 'undo', so your server
follows.
Repeating events
Section titled “Repeating events”Drag one occurrence of a weekly meeting: is it this one, this one and the following, or all of them? By default the calendar asks, in a small menu where the event was dropped — “This event”, “This and following events”, “All events”; close the menu and the event goes back. The same question comes for a resize and for the Delete key (the menu has its own entries). A drag that turns an occurrence from timed to all-day, or back, changes that occurrence only and does not ask.
To answer yourself — your own dialog, or a rule — give
chooseScope a function. It is told the
occurrence and the kind of change, and returns 'this', 'following',
'all' or null to cancel, at once or as a promise.
import { createCalendar } from '@dzcalendar/dom';
declare function askScope(): Promise<'this' | 'following' | 'all' | null>;
createCalendar(element, { timeZone: 'Europe/Paris', editable: true, events: [{ id: 'staff', title: 'Staff meeting', start: '2026-10-19T09:00[Europe/Paris]', rrule: 'FREQ=WEEKLY' }], // Delete key: only this one. A drag or a resize: your own dialog, which may cancel. chooseScope: async ({ kind }) => (kind === 'delete' ? 'this' : ((await askScope()) ?? null)),});Recurrence shows what the store keeps for each answer. Try it: drag “Rounds” in the month and choose.
Dragging in from the page
Section titled “Dragging in from the page”A waiting list, a task, a template “Consultation, 30 min”: an element of the page becomes an event when it is dropped on the calendar. It takes two things:
droppableon the calendar:true, or a filter given the element’s data that says whether this one is welcome.makeDraggable(element, spec), from@dzcalendar/dom/drag, on each element.spec.eventis the event it becomes, without a start — the drop gives one;spec.datais yours (a patient’s id) and comes back inonDrop. It returns its own clean-up.
The event is made by a command checked as a gesture is — your rules apply,
and allow is told the event comes from outside (placement.external). Once
it is made, onDrop hears the place and your data, then
onEventReceive the change, with
revert(); one undo takes it back. It does not reach onEventChange:
persist it once, in onEventReceive.
import { createCalendar } from '@dzcalendar/dom';import { makeDraggable } from '@dzcalendar/dom/drag';
const card = document.getElementById('patient-42')!;const stop = makeDraggable(card, { event: { title: 'Consultation', duration: { minutes: 30 } }, data: { patientId: 42 },});
createCalendar(element, { timeZone: 'Europe/Paris', // Only patients' cards, not the other draggable things of the page. droppable: (data) => typeof data === 'object' && data !== null && 'patientId' in data, // Booked: the card leaves the waiting list. onDrop: (drop) => drop.element?.remove(), // The event that was made: persist it, or take it back. onEventReceive: (change) => { fetch('/api/events', { method: 'POST', body: JSON.stringify({ start: change.after?.start.toString() }) }) .then((res) => { if (!res.ok) change.revert(); }); },});
// When the card goes away from the page for good:stop();import { Component } from '@angular/core';import type { EventChange } from '@dzcalendar/dom';import { DZ_CALENDAR } from '@dzcalendar/angular';
// The cards: makeDraggable, as in plain JS.@Component({ selector: 'app-agenda', imports: [DZ_CALENDAR], template: `<dz-calendar timeZone="Europe/Paris" [options]="{ droppable: true }" (dropped)="$event.element?.remove()" (eventReceive)="save($event)" />`,})export class Agenda { save(change: EventChange): void { console.log('persist', change.after?.id); // change.revert() if the server says no }}<script setup lang="ts">import type { DropInfo, EventChange } from '@dzcalendar/dom';import { DzCalendar } from '@dzcalendar/vue';
const booked = (drop: DropInfo) => drop.element?.remove();// change.revert() if the server says no.const save = (change: EventChange) => console.log('persist', change.after?.id);</script>
<template> <DzCalendar time-zone="Europe/Paris" :options="{ droppable: true }" @dropped="booked" @event-receive="save" /></template>In React they are props of the same names; Angular’s output is (dropped), not (drop), and Vue’s @dropped.
With the pointer, the drag starts after a press and a short move on the
element (a finger holds still 300 ms first). Over a calendar that takes it,
the place under the pointer is drawn as the event would be, and the calendar
scrolls when the pointer nears its edge — but it does not change period, so
the day must be in the period shown. Release to drop; Escape, or releasing
outside every calendar, cancels. A refused place is drawn as such and reaches
onProposalRefused; nothing is made.
With the keyboard, makeDraggable makes the element focusable and gives it
role="button" when it has no role. Enter or Space picks it up, Tab reaches a
calendar, the arrows move the place as they move an event, Enter puts it
down, Escape cancels; each step is announced in the calendar’s language.
Someone who cannot drag can still put a patient on an hour.
To get the drop without the event, give the element create: false:
nothing is made and onDrop alone is told. event can also be a function,
read when each drag starts, so a list whose cards change stays right:
import { makeDraggable } from '@dzcalendar/dom/drag';
declare const row: HTMLElement;declare const task: { id: string; title: string; minutes: number };
makeDraggable(row, { // Read at the start of each drag. event: () => ({ title: task.title, duration: { minutes: task.minutes } }), data: task, // The application books it itself, from onDrop. create: false,});A calendar inside an iframe cannot be reached from the page around it.
Between two calendars
Section titled “Between two calendars”An event dragged out of a calendar can be dropped on another one of the page
when the first is editable and the second droppable — and editable too,
unless the event says it is editable itself. A droppable filter is given
the event. The calendar under the pointer shows the place.
The event is made on the receiving side first, then removed from the first.
If the first can no longer let it go, the second takes it back without being
told, the first’s onCommandRefused hears the refused removal, and “Action
refused” is announced. Once both
are done, the second hears
onEventReceive and the first
onEventLeave, with the event and to,
the other calendar’s view element.
import { createCalendar } from '@dzcalendar/dom';
declare const left: HTMLElement;declare const right: HTMLElement;
createCalendar(left, { timeZone: 'Europe/Paris', editable: true, onEventLeave: (leave) => console.log(leave.event.title, 'left') });// Persist the move once, from the receiving side.createCalendar(right, { timeZone: 'Europe/Paris', editable: true, droppable: true, onEventReceive: (change) => console.log('received', change.after?.id) });In the frameworks they are outputs: Angular’s (eventLeave) and (eventReceive), React’s onEventLeave and onEventReceive, Vue’s @event-leave and @event-receive.
What to know about this drop:
- Each calendar has its own history: a create on one side, a delete on the
other. An undo on one side alone would leave the event on both or on
neither; use
revert(), from either callback, which takes back both sides — or returnsfalse, doing nothing, if either changed since. - An occurrence of a series goes alone; the series stays.
- Two calendars on one store (several zones of one agenda) share the
event: the drag is a plain move, told to the receiving side’s
onEventReceive, andonEventLeaveis not called. - An event released outside every calendar lands nowhere; a few pixels past the edge still count as on it.
See also
Section titled “See also”editable,snapMinutes,eventResizableFromStart,dragEdgeNavigate— what a person may do.rules,onProposalRefusedandonCommandRefused— what refuses a drop, and why.droppable,onDropandonEventLeave— events coming in and going out.- Events — commands, the history and saving.
- Recurrence — the series behind the scope question.
- Keyboard and accessibility — the same moves without a pointer.
- Selection — dragging across empty time.