Theming & CSS
The calendar looks right with one stylesheet, and a page can change all of it without fighting it: tokens for colours and sizes, plain CSS rules that always win, and themes of your own. Tailwind setup is in its own guide, and a calendar drawn entirely by you in Unstyled mode.
Pick a family
Section titled “Pick a family”Import the stylesheet once. Seven families come with it, each with a light and
a dark palette: 'standard' (the default), 'slate', 'night', 'pastel',
'frost', 'solar' and 'contrast' (high contrast). All are checked for
WCAG AA contrast. theme names the family,
scheme the side and
density the scale:
import '@dzcalendar/theme/dzcalendar.css';import { createCalendar } from '@dzcalendar/dom';
createCalendar(element, { theme: 'slate', scheme: 'auto', density: 'comfortable' });import { Component } from '@angular/core';import { DZ_CALENDAR } from '@dzcalendar/angular';
// angular.json: "styles": ["node_modules/@dzcalendar/theme/dzcalendar.css"]@Component({ selector: 'app-agenda', imports: [DZ_CALENDAR], template: `<dz-calendar theme="slate" scheme="auto" density="comfortable" />`,})export class Agenda {}import '@dzcalendar/theme/dzcalendar.css';import { DzCalendar } from '@dzcalendar/react';
export function Agenda() { return <DzCalendar theme="slate" scheme="auto" density="comfortable" />;}<script setup lang="ts">import '@dzcalendar/theme/dzcalendar.css';import { DzCalendar } from '@dzcalendar/vue';</script>
<template> <DzCalendar theme="slate" scheme="auto" density="comfortable" /></template>Without the stylesheet the calendar still works, in system colours, but the
ready-made families live in that CSS: without it they change nothing. All
three options change live (update({ theme: 'night' })), and an unknown
value is refused with a RangeError (from createCalendar and update; in
React, Vue and Angular it goes to the wrapper’s error path).
THEME_NAMES, exported by @dzcalendar/dom, lists the families.
Light and dark
Section titled “Light and dark”scheme: 'auto' follows the system’s prefers-color-scheme; 'light' and
'dark' force a side. A site switch that writes data-theme="dark" or
"light" on an ancestor (<html>, say) needs no update at all with
'auto': the calendar follows it, as it follows the system. For a toggle of
the calendar’s own, call update({ scheme }) (see
scheme):
toggle.addEventListener('change', () => calendar.update({ scheme: toggle.checked ? 'dark' : 'light' }));Each family’s two palettes are plain values, switched by scheme, by a
data-theme attribute and by the media query: nothing needs
light-dark() support. The demos of this site follow the switch at the top of
the page unless they set scheme themselves.
Density and event style
Section titled “Density and event style”density sets the height of a minute (0.8, 1.2 and
1.6 px for 'compact', 'comfortable' and 'spacious', so 48, 72 and 96 px
an hour), of a bar and the type size. Any other scale is one token:
.dz-cal { --dz-minute: 2px; } makes 120 px an hour (on .dz-cal
itself, or a class on it: the densities set the token there).
eventStyle is 'tinted' (the default: a tint
of the event’s tone, its edge in the tone) or 'solid' (a block of the tone,
its text in --dz-on-tone, white on the light scheme and near-black on the
dark one, so contrast holds in both; a pale tone of your own takes
--dz-tone-<name>-on).
In Angular and Vue, eventStyle goes through options; in React it is a prop.
Change a colour
Section titled “Change a colour”The palette is shared with tzslot (--tz-*), so a page using both libraries
sets it once; the calendar’s own tokens are --dz-*. The ones you will reach
for:
| Token | What it sets |
|---|---|
--tz-bg, --tz-bg-raised |
the page background, and the raised surface of hovers (toolbar buttons, “+N”, menu items) and of the list view’s day headings |
--tz-fg, --tz-fg-muted |
text, secondary text |
--tz-border |
lines |
--tz-accent, --tz-accent-fg |
the accent (today, selected view, focus) and the text on it |
--tz-danger, --tz-warning |
refusals and the now line (--dz-now’s default); clock-change marks |
--tz-radius, --tz-font |
corner radius, font |
--dz-today-bg, --dz-now |
today’s cell or column, the current-time line |
--dz-event-bg, --dz-event-fg, --dz-event-accent, --dz-event-radius |
events |
--dz-tone-<name> |
a named event tone (tone: 'green' on an event) |
--dz-on-tone, --dz-tone-<name>-on |
the text on a solid event, for every tone or for one |
--dz-height, --dz-minute, --dz-bar-height, --dz-gutter-width |
sizes |
Every --tz-x has a --dz-x override on the calendar. The family’s tokens
and tones (--dz-*) are declared on the calendar itself, so set them on
.dz-cal or a class on it: on :root or an ancestor they never reach the
events. The page’s --tz-* is the exception, below.
:root { --tz-accent: #0a7d5a; } /* every family follows */.dz-cal.agenda { --dz-radius: 2px; --dz-tone-green: #0a7d5a; } /* this calendar only */The page comes first. A family gives defaults: the calendar reads
--dz-x, else the page’s --tz-x (on :root or any ancestor), else the
family’s, else a system colour. So a --tz-accent on :root recolours a
'slate' calendar too. The flip side: a page that loads tzslot’s theme shows
tzslot’s palette whatever family is chosen. Set --tz-* on the calendar or an
ancestor, not on an event; an event has --dz-event-* and its tone. A value
may be a light-dark(light, dark) pair where the browser has it.
Your rules win
Section titled “Your rules win”All of the calendar’s CSS sits in two cascade layers, dzcalendar.base then
dzcalendar.theme, the Pro’s timeline and editor sheets included. Any rule of yours outside a layer wins over both,
whatever its specificity: no !important, no copying our selectors.
Every part, state and token you may rely on
is listed, and a rename there is a major version.
.dz-ev { border-radius: 0; } /* square events */.dz-toolbar { display: none; } /* your own header */.dz-cal [data-today] { outline: 2px solid var(--tz-accent); }The one exception is the grabbing cursor while an event is dragged, which is
!important in the base layer. Layers need Chrome 99, Safari 15.4 or
Firefox 97. A page whose reset is not layered (Bootstrap, Tailwind 3) sets
cssLayers to false and imports the unlayered
theme (@dzcalendar/theme/unlayered.css, or tailwind3.css): see the
Tailwind guide. To keep the structure and draw everything
yourself, look: 'none' and the render
hooks are in Unstyled mode.
A theme of your own
Section titled “A theme of your own”defineTheme(name, tokens) registers a family that builds on the standard
one: what it gives wins, what it leaves out (the palette, the named tones
green, red…, --dz-on-tone) is standard’s, provided the theme CSS is
loaded; without it, what is left out falls to system colours. It registers a
family from the palette, the
calendar’s own tokens (todayBg, now, eventBg, eventFg, eventAccent)
and named event tones. A colour is one value or a [light, dark] pair;
radius and font are one value. Call it before the calendar is made:
import { createCalendar, defineTheme } from '@dzcalendar/dom';
defineTheme('clinic', { accent: ['#0a7d5a', '#3ddc97'], bg: ['#ffffff', '#0f1915'], radius: '4px', tones: { urgent: ['#b91c1c', '#f87171'] },});
createCalendar(element, { theme: 'clinic' });// an event with tone: 'urgent' takes the clinic's redYour theme is injected in the dzcalendar.theme layer, so your plain CSS and
your page’s --tz-* still win. Only the tokens above are accepted; an unknown
token, a ready-made name, a name that is not lowercase letters, digits and
dashes, a tone name with other characters or an unsafe value (;, {,
url() is refused with a RangeError. Defined again, the calendars using it follow at once.
If you build the stylesheet yourself, the SCSS variables are !default.
They change the standard family only, so every defineTheme family built on
it too; the six others come from $themes:
@use '@dzcalendar/theme/dzcalendar' with ( $accent: (#0a7d5a, #3ddc97), $bg: (#ffffff, #0f1915));Shadow roots and a strict CSP
Section titled “Shadow roots and a strict CSP”The page’s sheets do not cross a shadow root. With the <dz-calendar>
element of @dzcalendar/element (import '@dzcalendar/element/define') and
its shadow attribute, the calendar injects its own CSS inside, and the
palette (--tz-*, --dz-*) is inherited through the root. Link the theme in
(stylesheet="/path/dzcalendar.css") or load it inside the root when you
mount createCalendar in one; defineTheme themes are put there by the
calendar itself. Style the element from outside with ::part(calendar) and
::part(toolbar). The Angular <dz-calendar> is another component and has
neither attribute. One limit: inside a shadow root, a page ancestor’s
data-theme does not switch the palette (the selectors do not cross the
boundary, and :host-context is missing in Safari and Firefox), and none on
the host element helps either. Pass scheme to the calendar; 'auto' still
follows the system.
A Content-Security-Policy without inline styles refuses the <style> the
calendar adds. Set injectStyles to false
and include the CSS in a stylesheet your policy allows:
import { DZ_CSS, themeCss, createCalendar } from '@dzcalendar/dom';import { LIST_CSS } from '@dzcalendar/dom/list';import { MULTIMONTH_CSS } from '@dzcalendar/dom/multimonth';import { TIMELINE_CSS } from '@dzcalendar/pro';import { EDITOR_CSS } from '@dzcalendar/pro/editor';
// Write these into your own stylesheet at build time, after the theme's// dzcalendar.css; defineTheme('clinic', …) still runs in the app, before createCalendar:const sheet = [DZ_CSS, LIST_CSS, MULTIMONTH_CSS, TIMELINE_CSS, EDITOR_CSS, themeCss('clinic')].join('\n');
createCalendar(element, { injectStyles: false, theme: 'clinic' });Add each sheet only for the views you import, with the theme stylesheet itself
(@dzcalendar/theme/dzcalendar.css) and themeCss(…) for a defineTheme
family. An unknown theme is refused by createCalendar, so the family must
be defined first. With look: 'none', pass each sheet through
lookGuardedCss(…), from @dzcalendar/dom/toolkit. Titles and day numbers
in another calendar (Hijri, Persian) are
displayCalendar.