Print & export (Pro)
A calendar ends up on paper, in a spreadsheet, or in somebody else’s
calendar app. The Pro (@dzcalendar/pro) does all three with no dependency
of its own: it prints real sheets, writes a PDF, PNG images, an Excel sheet,
a CSV file and an iCalendar file, and every one of them keeps each event’s
time zone and the true length of a day with a clock change. The print and
the exports are two entries of their own, @dzcalendar/pro/print and
@dzcalendar/pro/export: import them where they are used (or with
import()), and the rest of the application does not carry them. The
framework packages below fetch them on first use by themselves.
Printing the calendar as it is
Section titled “Printing the calendar as it is”Without the Pro, the browser’s own print already works, with one catch: a calendar windows what is off screen and hides crowded days behind “+N”. Ask it to draw everything first, then put things back:
const restore = calendar.preparePrint();window.print();restore();With autoPrint set to true when the
calendar is made, it does this by itself around the browser’s beforeprint
and afterprint, so the browser’s Print command (Ctrl+P) is enough. What is
printed is the calendar as it is on screen, without the toolbar’s buttons
and with what scrolls printed whole, on the page as the browser lays it out.
With @dzcalendar/theme, colours print as they are on screen (the theme
asks the browser not to lighten backgrounds). The calendar’s own rules sit
in cascade layers, so a print rule of your page outside a layer overrides
them; see cssLayers when it does not.
Printing sheets
Section titled “Printing sheets”When the calendar must come out as proper sheets of paper, a week to a
sheet, use printPages:
import { printPages } from '@dzcalendar/pro/print';
const job = await printPages(calendar); // the period shown, A4 landscapeIt builds, off screen, a copy of the calendar for each period of the view
(a day, a week, a month), sized to the sheet, with the period’s title on top
and “1 / 3” at the foot; then it calls window.print(). The copies share
the calendar’s store, so nothing is fetched again, and they keep its look
and options but none of its handlers, motion or context menu. Paper is
always light, whatever the scheme on screen.
What the sheets show:
- A time grid has its hours stretched to fill the height of the sheet.
- A month has its weeks stretched too, each day showing as many events as it holds room for (a “+N” link past that, as on screen).
- A list runs over as many sheets as it takes, portrait by default.
- A timeline has its slots stretched across the width. A resource
timeline is split between sheets by whole top-level resources (a parent
stays with its children);
rowsPerPagesets how many rows a sheet holds. - A multi-month view prints one month a sheet.
- There is no “now” line on paper.
The browser draws the text, so any script prints, and “Save as PDF” in the
print dialog keeps it selectable. Only one print job exists per document:
calling printPages again, or destroying the calendar, closes the first.
The sheets are taken away after printing by themselves.
To build the sheets without printing them (to check them in a test, or to
print later yourself), ask for print: false: the job holds them in
job.pages, off screen, with its problems, and nothing takes them away
until you call job.close().
Choosing the period and the paper
Section titled “Choosing the period and the paper”Printing and the image exports (PDF and PNG) take the same options:
import { Temporal } from '@dzcalendar/core';import { printPages } from '@dzcalendar/pro/print';
await printPages(calendar, { view: 'dayGridMonth', from: Temporal.PlainDate.from('2026-10-01'), to: Temporal.PlainDate.from('2026-12-01'), // exclusive: October and November paper: 'letter', orientation: 'portrait',});| Option | What it does |
|---|---|
view |
The view to put on paper; the one shown by default. It need not be the one on screen: print the month from a week view |
from, to |
[from, to), as dates in the calendar’s zone; by default one period of the view around the date shown (from alone: one period from it) |
paper |
'a4' (the default), 'letter' or 'a3' |
orientation |
'landscape', or 'portrait' for a list, by default |
printPages takes three more: rowsPerPage (above), print (below) and
messages (see The words of the files).
The dates are cut into the view’s own periods: three months of a month view
are three sheets. At most 60 periods come out, and a PDF or PNG export
stops at 300 sheets; past that, a cut:60 or cut:300 warning says so.
One function per format
Section titled “One function per format”Each export takes the calendar and resolves with a file in memory, a
Blob (exportPNG: a list of them, blobs), and the problems met along
the way:
| Function | File | Over |
|---|---|---|
exportPDF |
PDF, a sheet a page | a view and its dates, like printing |
exportPNG |
PNG images, one per sheet | a view and its dates, like printing |
exportXLSX |
Excel sheet | a range of dates |
exportCSV |
CSV, comma, semicolon or tab separated | a range of dates |
exportICS |
iCalendar (.ics) |
a range of dates, or everything |
The three that list events take from and to too ([from, to), dates in
the calendar’s zone) and default to what the view shows. They fetch the
range first, through your sources, and a range that
could not be loaded is a warning: the file is made without it, and the
result’s problems say so.
A spreadsheet: XLSX and CSV
Section titled “A spreadsheet: XLSX and CSV”import { exportCSV, exportXLSX } from '@dzcalendar/pro/export';
const { blob, problems } = await exportXLSX(calendar, { from, to });const csv = await exportCSV(calendar, { separator: ';' }); // a French ExcelBoth write the same table, one row per occurrence, in order of start: a
recurring event is spread into its occurrences, each once; background
events are left out. The columns are the title; the
start and its time zone; the end and its own time zone; the start and end
in the calendar’s timeZone; the duration in
minutes; all day; the resources by title; the status.
That is how time zones survive a spreadsheet, which has none of its own:
- The start is written in the event’s zone, with that zone beside it. The end has its own zone: a flight Paris to Tokyo ends at 07:00 in Asia/Tokyo.
- The same moments are written again in the calendar’s zone, for a reader who wants one clock.
- The duration is the real elapsed time: 00:00 to 06:00 on the night the clocks go back says 420 minutes, not 360.
- An all-day event has dates, no zone and no duration; its end is the day after its last (exclusive), as in the calendar.
In the XLSX, dates are real Excel dates (what the cell says is what that
zone’s clock said), the head row is frozen and filtered, and the sheet reads
right to left when the calendar does (Arabic, Hebrew). Excel has no date
before 1900: such a time is written as text. The CSV writes times as
2026-10-25 06:00 and dates as 2026-10-25, in UTF-8 with a byte-order
mark and CRLF line ends, which Excel opens correctly; a cell starting with
=, +, - or @ is written as text, so a spreadsheet never runs it as
a formula.
A PDF or images
Section titled “A PDF or images”import { exportPDF, exportPNG } from '@dzcalendar/pro/export';
const { blob } = await exportPDF(calendar, { from, to, paper: 'a4', title: 'October' });const { blobs } = await exportPNG(calendar, { scale: 2 }); // one image per sheetUnlike printing, these draw the view on a canvas from the calendar’s model, so they need no print dialog: a time grid with its resources, a month, a list over as many sheets as it takes (a day’s head repeated on each), a timeline with its heads repeated. A day of 23 or 25 hours is drawn as it is: the repeated hour is striped, and a timeline day is 25 hours wide. A right-to-left calendar is drawn right to left. The calendar’s zone is written in the top corner of each sheet, beside the period’s title.
Two things to know. The PDF holds the sheets as pictures (one JPEG a page),
so its text is not selectable (use printing and “Save as PDF” for
selectable text), and the file grows with each sheet and with scale. And
the colours are the light palette, whatever the scheme on screen.
scale is the device pixels per CSS pixel, 2 by default (192 dpi), up to
4. title names the PDF; by default it is the period.
An iCalendar file
Section titled “An iCalendar file”import { exportICS } from '@dzcalendar/pro/export';
const { blob } = await exportICS(calendar, { from, to, name: 'Clinic' });const everything = await exportICS(calendar, { all: true });An .ics file keeps what a spreadsheet flattens. An event is written as it
is: its start and its end each in its own zone (TZID), with a
VTIMEZONE for each zone, drawn from the zone’s real clock changes, so
that every calendar app places it at the right moment; an event in UTC is
written in UTC. A recurring series is written whole, once, whichever of
its occurrences the range shows: its rule (RRULE), its excluded and added
dates (EXDATE, RDATE), and each occurrence that was moved or edited, as
an event of the same UID with a RECURRENCE-ID (see
Recurrence). An all-day event is a date, with no zone.
By default the file holds what the range shows, background events
included — marked transparent (TRANSP:TRANSPARENT), so they take no one’s
time where the file is imported; all: true writes everything the calendar has loaded. name
becomes the calendar’s name in the file (X-WR-CALNAME). This is the format to give another calendar app; to read a feed in,
see Event sources.
The words of the files
Section titled “The words of the files”The column heads, the statuses and “1 / 3” come in English, French, Arabic,
Spanish and German, chosen by the calendar’s
locale; any other language falls back to
English. Change any of them with messages, which takes only the words to
replace, or add a whole language with defineExportLocale:
await exportCSV(calendar, { messages: { title: 'Intitulé', allDay: 'Toute la journée' } });“All day” and “No events” follow the calendar’s own
messages. More on languages in
Languages.
Saving the file
Section titled “Saving the file”A Blob is not yet a download. download saves one through the browser:
import { download, exportXLSX } from '@dzcalendar/pro/export';
const { blob } = await exportXLSX(calendar);if (blob) download(blob, 'agenda.xlsx');Or make and save in one call with downloadExport(calendar, kind, filename, options), where kind is 'pdf', 'png', 'xlsx', 'csv' or 'ics'.
It resolves with the problems met, and never rejects: with no error among
them, the file was saved. A PNG export of several sheets is saved as one
zip, agenda.zip holding agenda-1.png, agenda-2.png…
A button in each framework
Section titled “A button in each framework”The frameworks’ Pro packages do the same through the calendar they hold, and fetch the print and the exports when first used. Make the calendar’s controller, give it to the calendar, and call the exports from your own buttons:
import { createCalendar } from '@dzcalendar/dom';import { downloadExport } from '@dzcalendar/pro/export';import { printPages } from '@dzcalendar/pro/print';
const calendar = createCalendar(element, { timeZone: 'Europe/Paris', initialView: 'timeGridWeek' });
document.getElementById('print')!.addEventListener('click', () => void printPages(calendar));document.getElementById('csv')!.addEventListener('click', async () => { const problems = await downloadExport(calendar, 'csv', 'agenda.csv', { separator: ';' }); if (problems.length > 0) console.warn(problems);});import { Component, inject } from '@angular/core';import { DZ_CALENDAR } from '@dzcalendar/angular';import { DzExport } from '@dzcalendar/pro-angular';
@Component({ selector: 'app-agenda', imports: [DZ_CALENDAR], template: ` <dz-calendar #cal timeZone="Europe/Paris" /> <button (click)="exports.print(cal.controller)">Print</button> <button (click)="exports.download(cal.controller, 'pdf', 'agenda.pdf')">PDF</button> <button (click)="exports.download(cal.controller, 'csv', 'agenda.csv', { separator: ';' })">CSV</button>`,})export class Agenda { readonly exports = inject(DzExport);}import { DzCalendar, useCalendarController } from '@dzcalendar/react';import { useDzExport } from '@dzcalendar/pro-react';
export function Agenda() { const cal = useCalendarController(); const exports = useDzExport(cal); return ( <> <DzCalendar timeZone="Europe/Paris" controller={cal} /> <button onClick={() => void exports.print()}>Print</button> <button onClick={() => void exports.download('pdf', 'agenda.pdf')}>PDF</button> <button onClick={() => void exports.download('csv', 'agenda.csv', { separator: ';' })}>CSV</button> </> );}<script setup lang="ts">import { DzCalendar, createCalendarController } from '@dzcalendar/vue';import { useDzExport } from '@dzcalendar/pro-vue';
const cal = createCalendarController();const exports = useDzExport(cal);</script>
<template> <DzCalendar time-zone="Europe/Paris" :controller="cal" /> <button @click="exports.print()">Print</button> <button @click="exports.download('pdf', 'agenda.pdf')">PDF</button> <button @click="exports.download('csv', 'agenda.csv', { separator: ';' })">CSV</button></template>In Angular, DzExport takes the component’s controller (as above), the
<dz-calendar> itself, or the calendar of @dzcalendar/dom. The same
exports, pdf, png, xlsx, csv, ics and print, are methods of
exports in React and Vue, and of DzExport in Angular (with the calendar
as first argument).
When something goes wrong
Section titled “When something goes wrong”Bad input never throws. A result carries problems, each with the code
invalid-export, a path (what was wrong) and a short detail. An
error means no file (blob: null, no blobs, no sheets): an unknown
view, or one whose family is not loaded; a from or to that is not a
Temporal.PlainDate, or a range that ends before it starts; a paper that
is not a4, letter or a3; a separator that is not ,, ; or tab;
in a framework, a calendar not yet mounted (not-attached).
A warning means the file was made anyway: a guess (a scale,
orientation or rowsPerPage that is not one, replaced by its default), a
range of dates that could not be fetched (sources), a cut past 60 periods
or 300 sheets, or, when printing, a sheet that could not hold everything
(clipped:2, the number being the sheet).