subDomain

Specify all options related to the subDomain configuration

type subDomain: {
  type: string,
  gutter: number,
  width: number,
  height: number,
  radius: number,
  label:
    | string
    | null
    | ((timestamp: number, value: number, element: SVGElement) => string);
  color?:
    | string
    | ((timestamp: number, value: number, backgroundColor: string) => string);
}

type

SubDomain’s type, representing a time unit

type: string,

The subDomain should always be smaller than the domain type.

Available default subDomains type

month
week
day
x_day
hour
minute

See Examples

You can create and add your own custom subDomain, see the Templates section.

gutter

Space between each subDomain, in pixel

gutter: number,

Default: 2

Playground

Gutter: 4 pixels

width

Width of each subDomain cell, in pixel

width: number,

Default: 10

Playground

Width: 10 pixels

height

Height of each subDomain cell, in pixel

height: number,

Default: 10

Playground

Height: 10 pixels

radius

Border radius of each subDomain cell, in pixel

radius: number,

Default: 0

Radius: 0 pixels

label

Label of the subDomain

label:
    | string
    | null
    | ((timestamp: number, value: number, element: SVGElement) => string);

Default: null

This option accepts different value’s type, see table below for usage.

Value Type	Description	Example Value	Example output
`string`	Pass the string to dayjs `format()`, and display its result. (not value aware)	`MMMM`	`March`
`null`	Do not show any label	`null`
`function`	Display the function’s return value. The function takes the subDomain’s timestamp, value and the label’s SVG Element as argument	function (timestamp, value) { return `${value} items on ${new Date(date).toISOString()}`; }	`50 items on 2022-12-06T20:01:51.290Z`

dayjs format() is locale and timezone aware.

Depending on your chosen cell size, subDomain label may overflow

You can customize the style of the subDomain label text via css, or by manipulating the SVGElement given as argument when using a function.

Example

const cal = new CalHeatmap();
cal.paint({
  domain: { type: 'month' },
  subDomain: { type: 'day', label: 'D', width: 20, height: 20, color: '#000' },
  range: 3
});

color

Color of the subDomain’s label

color?:
| string
| ((timestamp: number, value: number, backgroundColor: string) => string);

Default:

d3.hcl(backgroundColor).l > 60 ? 'black' : 'white';

This option accepts different value’s type, see table below for usage.

Value Type	Description	Example Value	Example Output
`string`	A hexadecimal color code	`#000`	`#000`
`function`	Use the hexadecimal color code returned by the function. The function takes the subDomain’s timestamp, value and background color as argument	`function (timestamp, value, backgroundColor) { return d3.hcl(backgroundColor).l > 60 ? 'black' : 'white' ; }`	`#000`

Using the string value, the same color will be applied to the whole calendar, regardless of the subDomain’s background color. Depending on your color scale, the label color may not be readable.

Using a function will allow more fine-tuning of the label color, as you can use:

a d3-color scale
a range of static colors (i.e ['#fff', '#eee', '#000'], matching the scale's range)
a custom function returning a color, computed from the background color (like the default value)