Skip to content

timeline

The scale and the lanes of the Pro’s timeline views (import '@dzcalendar/pro').

Type{ readonly slot?: number | 'day'; readonly maxLanes?: number; readonly fillLanes?: number; readonly step?: DurationLike | undefined; readonly follow?: boolean | { readonly before?: DurationLike } | undefined; readonly ticks?: number | { readonly every: number; readonly label?: number } | undefined; readonly span?: DurationLike | undefined }
Defaultnot set
Live update (update())Yes
Declared inpackages/core/src/kernel.ts

The timeline draws time across, a row per resource (resourceTimelineDay, …Week, …Month, …Year) or one row for all (timelineDay…). Seven settings, merged key by key with update({ timeline }) — slot: undefined goes back to the default:

  • slot: the width of a slot in time.
  • maxLanes: the lanes of a resource’s row; the last one holds “+N” when more events overlap.
  • fillLanes: the lanes of a timeline without resources — a starting value: in a browser its one row fills the view and the lanes are measured.
  • step: what ◀ ▶ slide the timeline by ({ minutes: 15 }, { hours: 1 }) instead of changing period.
  • follow: the timeline keeps the present in view as time passes.
  • span: the time shown at once ({ hours: 4 }), whatever the room.
  • ticks: a small tick every so many minutes inside each slot.

A slot that is a whole number of minutes must divide a day, and the lanes are whole numbers of 1 or more; a step is hours and minutes, longer than nothing, a span days, hours and minutes; anything else throws a RangeError at creation or update(). A wall-clock slot crossing a clock change keeps its true width. The width on screen is the stylesheet’s (--dz-tl-slot) unless a span sets it; the resource area’s columns are viewOptions.timeline.areaColumns.

Typenumber
Default12
Live update (update())Yes
Declared inpackages/core/src/kernel.ts

Lanes of a timeline without resources, before it is measured: in a browser its one row is as tall as the view and holds as many lanes as fit.

Typeboolean | { readonly before?: DurationLike } | undefined
Defaultfalse
Live update (update())Yes
Declared inpackages/core/src/kernel.ts

The present stays in view, its slot at the left edge (at 22:47 in quarters of an hour, 22:45), what comes after it shown; the timeline moves on when the next slot begins; past the end of the period (midnight on a day’s timeline) the next one comes in. It pauses as soon as the person moves along time — a scroll, a slide, another period — and “Today” (navigate('today')) takes it up again. Made for supervision: a timeline that shows what is running now.

Give it { before: { minutes: 5 } } and the present stays that far from the left edge instead — a little of what just happened in view — the axis gliding each minute: the motion adapter’s eased scroll (GSAP with @dzcalendar/motion-gsap), else the browser’s smooth one, at once under reduced motion. The glide is the view’s own: it does not pause following.

Typenumber
Default3
Live update (update())Yes
Declared inpackages/core/src/kernel.ts

Overlapping events a resource’s row stacks; past them its last lane holds “+N”, which opens the rest.

Typenumber | 'day'
Default30 minutes for a day, 60 up to a week, days beyond
Live update (update())Yes
Declared inpackages/core/src/kernel.ts

Minutes per slot (a divisor of a day: 15, 30, 60, 120…) or 'day'. By default 30 minutes for a day, an hour up to a week, a day beyond.

TypeDurationLike | undefined
Defaultnot set
Live update (update())Yes
Declared inpackages/core/src/kernel.ts

Hours and minutes ({ minutes: 15 }, { hours: 1 }, 'PT30M'). With it, ◀ ▶ and navigate('prev' | 'next') scroll the timeline by that much; at the end of the axis the next or previous period comes in, where the slide was going. A view of one day stops at midnight on the way; a view of several days (views: { supervision: { family: 'timeline', duration: { days: 3 } } }) slides across it. calendar.shift({ minutes: -45 }) slides by any other number of hours and minutes (a day or more, or nothing, throws a RangeError, as the option does). A day or more is a view’s dateIncrement, not a step.

Typenumber | { readonly every: number; readonly label?: number } | undefined
Defaultnot set
Live update (update())Yes
Declared inpackages/core/src/kernel.ts

As on a ruler: { every: 1, label: 5 } draws a short mark each minute and writes the time every fifth (label, a multiple of every); a number is both. As dense as the room allows: the times only with room for them, the minute marks only a few pixels apart — at 4 hours shown, the marks alone. Minutes between small ticks inside each slot: 5 in quarters of an hour draws 10:05 and 10:10 between 10:00 and 10:15 — a short mark and its time in the head, written smaller in a monospace font (--dz-tl-tick-font), and a fine dotted line through the rows. Drawn when it divides the slot and is shorter than it; whole minutes dividing a day, else a RangeError.

TypeDurationLike | undefined
Defaultnot set
Live update (update())Yes
Declared inpackages/core/src/kernel.ts

Days, hours and minutes ({ hours: 4 }, 'PT1H', { days: 1 }): the time on screen at once. A slot’s width is the room shared by that many slots, measured again when the calendar’s size changes — four hours fill a phone as they fill a wide screen. Longer than the period, the period fits; shorter than a slot, one slot fills it. Changed by update(), the moment at the centre of what is shown stays there, and the present keeps its place while follow is on: a window of four hours that slides with the clock. Pick a slot that suits it (24 hours in quarters of an hour are 96 narrow heads). Without it, the width is the stylesheet’s --dz-tl-slot.

import { createCalendar } from '@dzcalendar/dom';
import '@dzcalendar/pro';
const calendar = createCalendar(element, {
timeZone: 'Europe/Paris',
initialView: 'resourceTimelineWeek',
resources: [{ id: 'benali', title: 'Dr Benali' }, { id: 'room1', title: 'Room 1' }],
timeline: { slot: 120, maxLanes: 2 },
});
// Later: back to the default slot, lanes unchanged.
calendar.update({ timeline: { slot: undefined } });

In Angular and Vue it goes in options; in React it is a prop.

The day, a row per resource, a slot every hour (30 minutes by default).