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 } |
|---|---|
| Default | not set |
Live update (update()) | Yes |
| Declared in | packages/core/src/kernel.ts |
What it does
Section titled “What it does”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.
Its members
Section titled “Its members”fillLanes
Section titled “fillLanes”| Type | number |
|---|---|
| Default | 12 |
Live update (update()) | Yes |
| Declared in | packages/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.
follow
Section titled “follow”| Type | boolean | { readonly before?: DurationLike } | undefined |
|---|---|
| Default | false |
Live update (update()) | Yes |
| Declared in | packages/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.
maxLanes
Section titled “maxLanes”| Type | number |
|---|---|
| Default | 3 |
Live update (update()) | Yes |
| Declared in | packages/core/src/kernel.ts |
Overlapping events a resource’s row stacks; past them its last lane holds “+N”, which opens the rest.
| Type | number | 'day' |
|---|---|
| Default | 30 minutes for a day, 60 up to a week, days beyond |
Live update (update()) | Yes |
| Declared in | packages/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.
| Type | DurationLike | undefined |
|---|---|
| Default | not set |
Live update (update()) | Yes |
| Declared in | packages/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.
| Type | number | { readonly every: number; readonly label?: number } | undefined |
|---|---|
| Default | not set |
Live update (update()) | Yes |
| Declared in | packages/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.
| Type | DurationLike | undefined |
|---|---|
| Default | not set |
Live update (update()) | Yes |
| Declared in | packages/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.
Example
Section titled “Example”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 } });import { Component } from '@angular/core';import { DZ_CALENDAR } from '@dzcalendar/angular';import '@dzcalendar/pro';
@Component({ selector: 'app-planning', imports: [DZ_CALENDAR], template: `<dz-calendar timeZone="Europe/Paris" view="resourceTimelineWeek" [resources]="staff" [options]="{ timeline: { slot: 120 } }" />`,})export class Planning { readonly staff = [{ id: 'benali', title: 'Dr Benali' }, { id: 'room1', title: 'Room 1' }];}import { DzCalendar } from '@dzcalendar/react';import '@dzcalendar/pro';
const STAFF = [{ id: 'benali', title: 'Dr Benali' }, { id: 'room1', title: 'Room 1' }];
export function Planning() { return <DzCalendar timeZone="Europe/Paris" defaultView="resourceTimelineWeek" resources={STAFF} timeline={{ slot: 120 }} />;}<script setup lang="ts">import { DzCalendar } from '@dzcalendar/vue';import '@dzcalendar/pro';
const staff = [{ id: 'benali', title: 'Dr Benali' }, { id: 'room1', title: 'Room 1' }];</script>
<template> <DzCalendar time-zone="Europe/Paris" view="resourceTimelineWeek" :resources="staff" :options="{ timeline: { slot: 120 } }" /></template>In Angular and Vue it goes in options; in React it is a prop.
Live demo
Section titled “Live demo”The day, a row per resource, a slot every hour (30 minutes by default).
See also
Section titled “See also”resources— the rows.collapsedResources— folded branches.- Resources & timeline.
- Live supervision: span, step, follow, markers.