Skip to main content

date

Specify the calendar's time boundaries and settings

type DateOptions: {
start: Date;
min?: Date;
max?: Date;
highlight?: Date[];
locale: string | Partial<ILocale>;
timezone?: string
}

start

Start date of the calendar

start: Date;

Default: new Date() (today)

info

Date is rounded to the start of the domain's type.
If start is new Date(2000-06-16), and the chosen domain is month, the calendar will start on 2000-06-01 (start of the month).

min

Minimum allowed date. Used on navigation, to set a lower bound when navigating backward.

Should always be <= start

min?: Date;

Default: null

max

Maximum allowed date. Used on navigation, to set a upper bound when navigating forward.

Should always be >= start

max?: Date;

Default: null

highlight

Array of dates to highlight.
Highlighted subDomain cells are given a special class to make them standout.

highlight?: Date[];

Default: []

tip

See the highlight class in the CSS to customize its style

const cal = new CalHeatmap();
cal.paint({
date: {
highlight: [
new Date('2020-01-15'),
new Date(), // Highlight today
],
},
});

locale

Date locale.

locale: string | Partial<ILocale>;
// See https://github.com/iamkun/dayjs/blob/dev/types/locale/types.d.ts for ILocale definition

locale is used by the underlying Day.js library to set the language and locale specific function, such as the first day of the week (monday/sunday).

Default: en

This option behaves differently, depending on the type of the passed value.

Using a locale name

Pass a dayjs locale name, e.g. en, fr, etc ...

Using the french locale
const cal = new CalHeatmap();
cal.paint({
date: { locale: 'fr' },
});

See the list of supported locale on day.js repository.

tip

For performance reasons, only the en locale is included by default, and all other locales are loaded on-demand. You can save a few milliseconds by including the dayjs locale script directly in your <head>, e.g. <script src="https://cdn.jsdelivr.net/npm/dayjs@1/locale/zh-cn.js"></script>, after the cal-heatmap.js <script>

Using a partial locale definition

Extend the default en locale, by passing a partial dayjs locale object.

Change the start of the week to monday
const cal = new CalHeatmap();
cal.paint({
date: { locale: { weekStart: 1 } },
});
tip

A locale object without the name property will be considered as partial

Using a full locale definition

Pass a full locale object. See dayjs locale documentation for object structure, and its github repo for some examples.

Pass a full custom locale
const cal = new CalHeatmap();
cal.paint({
date: {
locale: {
// Name property is required in order to not consider this object as partial
name: 'x-pseudo',
weekdays:
'S~úñdá~ý_Mó~ñdáý~_Túé~sdáý~_Wéd~ñésd~áý_T~húrs~dáý_~Fríd~áý_S~átúr~dáý'.split(
'_'
),
months:
'J~áñúá~rý_F~ébrú~árý_~Márc~h_Áp~ríl_~Máý_~Júñé~_Júl~ý_Áú~gúst~_Sép~témb~ér_Ó~ctób~ér_Ñ~óvém~bér_~Décé~mbér'.split(
'_'
),
weekStart: 1,
weekdaysShort: 'S~úñ_~Móñ_~Túé_~Wéd_~Thú_~Frí_~Sát'.split('_'),
monthsShort:
'J~áñ_~Féb_~Már_~Ápr_~Máý_~Júñ_~Júl_~Áúg_~Sép_~Óct_~Ñóv_~Déc'.split(
'_'
),
weekdaysMin: 'S~ú_Mó~_Tú_~Wé_T~h_Fr~_Sá'.split('_'),
ordinal: n => n,
formats: {
LT: 'HH:mm',
LTS: 'HH:mm:ss',
L: 'DD/MM/YYYY',
LL: 'D MMMM YYYY',
LLL: 'D MMMM YYYY HH:mm',
LLLL: 'dddd, D MMMM YYYY HH:mm',
},
relativeTime: {
future: 'í~ñ %s',
past: '%s á~gó',
s: 'á ~féw ~sécó~ñds',
m: 'á ~míñ~úté',
mm: '%d m~íñú~tés',
h: 'á~ñ hó~úr',
hh: '%d h~óúrs',
d: 'á ~dáý',
dd: '%d d~áýs',
M: 'á ~móñ~th',
MM: '%d m~óñt~hs',
y: 'á ~ýéár',
yy: '%d ý~éárs',
},
},
},
});

timezone

Date timezone.

timezone?: string;

Default: guessed from user browser.

Accepts any string representing a IANA timezone canonical name.

const cal = new CalHeatmap();
cal.paint({
date: { timezone: 'Europe/Paris' },
});
info

See the list of TZ database timezone here