CalendarLabel

This plugin generates additional labels for the calendar x/y axis

Install

Add the legend plugin in your page's <head>, after cal-heatmap library <script>

<script src="https://unpkg.com/cal-heatmap/dist/plugins/CalendarLabel.min.js"></script>

The plugin is built-in in the core CalHeatmap, just import the module with

import CalendarLabel from 'cal-heatmap/plugins/CalendarLabel';

Usage

const cal = new CalHeatmap();
cal.paint({}, [[CalendarLabel, CALENDAR_LABEL_OPTIONS]]);

See CalendarLabelOptions for the full list of available options.

CalendarLabelOptions

interface CalendarLabelOptions = {
  enabled: boolean;
  text: () => string[];
  key?: string;
  position?: 'top' | 'right' | 'bottom' | 'left';
  padding: [number, number, number, number];;
  radius: number;
  width: number;
  height: number;
  gutter: number;
  textAlign: TextAlign;
};

`enabled`

Whether to enable the plugin

Default: true

`text`

A function which return an array of labels.

text: () => string[],

The number of returned result is up to you, and generally depends on the subDomain's type. The returned labels will be split evenly on the X/Y axis

`key`

Unique ID for the plugin instance, required when you're using multiple instance of the plugin

key?: string;

Example

const cal = new CalHeatmap();
cal.paint({}, [
  [CalendarLabel, { position: 'top', key: 'top' }],
  [CalendarLabel, { position: 'bottom', key: 'bottom' }],
]);

`position`

Position of the labels, relative to the calendar.

position?: 'top' | 'right' | 'bottom' | 'left';

Default: left

http://localhost:3000

Live Editor

const cal = new CalHeatmap();
cal.paint(
  {
    itemSelector: '#cal-label-position',
    range: 3,
    domain: { type: 'month' },
    subDomain: { type: 'day' },
  },
  [
    [
      CalendarLabel,
      {
        position: 'top',
        key: 'top',
        text: () => ['this', '', 'is', 'on', '', 'top'],
        width: 30,
        textAlign: 'middle',
        padding: [0, 0, 5, 0],
      },
    ],
    [
      CalendarLabel,
      {
        position: 'left',
        key: 'left',
        text: () => ['Mon', '', '', 'Thu', '', '', 'Sun'],
        textAlign: 'end',
        width: 30,
        padding: [0, 5, 0, 0],
      },
    ],
    [
      CalendarLabel,
      {
        position: 'bottom',
        key: 'bottom',
        text: () => ['', '', '', ''],
      },
    ],
    [
      CalendarLabel,
      {
        position: 'right',
        key: 'right',
        text: () => [0, 1, 2, 3, 4],
        padding: [0, 10, 0, 10],
      },
    ],
    [
      CalendarLabel,
      {
        position: 'right',
        key: 'right-2',
        text: () => [0, 1, 2, 3, 4, 5, 6],
      },
    ],
  ]
);

render(<div id="cal-label-position"></div>);

const cal = new CalHeatmap();
cal.paint(
  {
    itemSelector: '#cal-label-position',
    range: 3,
    domain: { type: 'month' },
    subDomain: { type: 'day' },
  },
  [
    [
      CalendarLabel,
      {
        position: 'top',
        key: 'top',
        text: () => ['this', '', 'is', 'on', '', 'top'],
        width: 30,
        textAlign: 'middle',
        padding: [0, 0, 5, 0],
      },
    ],
    [
      CalendarLabel,
      {
        position: 'left',
        key: 'left',
        text: () => ['Mon', '', '', 'Thu', '', '', 'Sun'],
        textAlign: 'end',
        width: 30,
        padding: [0, 5, 0, 0],
      },
    ],
    [
      CalendarLabel,
      {
        position: 'bottom',
        key: 'bottom',
        text: () => ['', '', '', ''],
      },
    ],
    [
      CalendarLabel,
      {
        position: 'right',
        key: 'right',
        text: () => [0, 1, 2, 3, 4],
        padding: [0, 10, 0, 10],
      },
    ],
    [
      CalendarLabel,
      {
        position: 'right',
        key: 'right-2',
        text: () => [0, 1, 2, 3, 4, 5, 6],
      },
    ],
  ]
);

render(<div id="cal-label-position"></div>);

Result

`padding`

Padding around the labels container, in pixel

padding: [number, number, number, number];

Expect an array of 4 numbers, in the same order as CSS padding property (top, right, bottom, left)

Default: [0, 0, 0, 0]

`radius`

Border radius of the label's background, in pixel

radius?: number,

Default: 0

`width`

Width of the label, in pixel

width?: number,

Default: subDomain's width

`height`

Height of the label, in pixel

height?: number,

Default: subDomains' height

caution

Total height can not be greater that the domain height

`gutter`

Space between each label, in pixel

gutter?: number,

Default: subDomains' gutter

`textAlign`

Horizontal alignment of the label

textAlign?: 'start' | 'middle' | 'end',

Default: middle

Styling

Text color

Default : inherit your parent text color

Overwrite the CSS with

.ch-plugin-calendar-label-text {
  fill: red;
}

/* Or if you have multiple instance  */
[data-key='my-custom-label'] .ch-plugin-calendar-label-text {
  fill: red;
}

[data-key='my-other-label'] .ch-plugin-calendar-label-text {
  fill: blue;
}

Background color

Default: transparent

Overwrite the CSS with

.ch-plugin-calendar-label-bg {
  fill: blue;
}

/* Or if you have multiple instance  */
[data-key='my-custom-label'] .ch-plugin-calendar-label-bg {
  fill: blue;
}

[data-key='my-other-label'] .ch-plugin-calendar-label-bg {
  fill: red;
}

CalendarLabel

Install​

Usage​

CalendarLabelOptions​

enabled​

text​

key​

Example​

position​

padding​

radius​

width​

height​

gutter​

textAlign​

Styling​

Text color​

Background color​