Skip to main content Link Menu Expand (external link) Document Search Copy Copied

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

width

Width of each subDomain cell, in pixel

width: number,

Default: 10

Playground

height

Height of each subDomain cell, in pixel

height: number,

Default: 10

Playground

radius

Border radius of each subDomain cell, in pixel

radius: number,

Default: 0

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)