# Calendar Heatmap

> A year of daily values as a grid of days.

Source: https://ngwr.dev/charts/calendar-heatmap  
Updated in v15

## Installation

Import the class, and `@use` the entry point in your global styles: without it the component renders unstyled.

```typescript
import { Component } from '@angular/core';
import { WrCalendarHeatmap } from 'ngwr/charts/calendar-heatmap';

@Component({ imports: [WrCalendarHeatmap] })
export class MyComponent {}
```

```scss
@use 'ngwr/charts/calendar-heatmap';
```

## Basic

```angular-html
<wr-calendar-heatmap [data]="contributions" />
```

## Tooltip

`[tooltip]="false"` falls back to the browser `title`.

```angular-html
<wr-calendar-heatmap [data]="contributions" [tooltip]="false" />
```

## API

| Name | Description | Type | Default |
| --- | --- | --- | --- |
| `data` | One entry per day — `{ date, value }`. Days you pass nothing for render as empty cells, so a sparse array is the normal shape rather than a gap. | `readonly WrHeatmapDatum[]` | `[]` |
| `ariaLabel` | Accessible name of the whole grid. Its cells are bare spans whose `title` a screen reader on a role-less element does not read, so the map used to be several hundred anonymous nodes with no name. Falls back to `calendarHeatmap.label`. | `string \| null` | `null` |
| `endDate` | Last day to render. | `string \| Date \| null` | `today` |
| `weeks` | Number of weeks (columns) to render. | `number` | `53` |
| `cellSize` | Cell side in CSS pixels. | `number` | `11` |
| `cellGap` | Pixel gap between cells. | `number` | `2` |
| `color` | Cell fill colour at full intensity. | `string` | `primary` |
| `emptyColor` | Background colour for zero-value days. | `string` | `color-mix(in srgb, var(--wr-border-base) 50%, transparent)` |
| `showLabels` | Show the weekday + month labels around the grid. | `boolean` | `true` |
| `tooltip` | Show a tooltip with the day and its count on hover. It is the sentence the square's `title` carried, so the `title` is written only while this is off — or the browser would open a second copy a moment later. | `boolean` | `true` |
| `valueFormat` | Writes each day's count in the tooltip and the `title`. `null` uses `Intl.NumberFormat` in `LOCALE_ID`. | `((value: number) => string) \| null` | `null` |

## Types

```angular-ts
interface WrHeatmapDatum {
  date: string | Date;
  value: number;
}
```

| Name | Description | Type | Default |
| --- | --- | --- | --- |
| `WrHeatmapDatum` | One contribution cell. | `interface` | — |
| `date`required | ISO date string (YYYY-MM-DD) or Date. | `string \| Date` | — |
| `value`required | Count for the day, shown as a shade. | `number` | — |

## CSS variables

Set these on the component's selector or a wrapper, not on `:root`: the defaults are declared on `ngwr/charts/calendar-heatmap`'s own element.

| Variable | Default | Declared on |
| --- | --- | --- |
| `--wr-calendar-heatmap-font-family` | `var(--wr-font-family-base)` | `.wr-calendar-heatmap` |
| `--wr-calendar-heatmap-grid-gap` | `var(--wr-space-sm)` | `.wr-calendar-heatmap` |
| `--wr-calendar-heatmap-month-font-size` | `var(--wr-text-xs)` | `.wr-calendar-heatmap` |
| `--wr-calendar-heatmap-weekday-font-size` | `var(--wr-text-xs)` | `.wr-calendar-heatmap` |
| `--wr-calendar-heatmap-weekday-line-height` | `var(--wr-leading-none)` | `.wr-calendar-heatmap` |

## Dependencies

| Built on | `ngwr/date`, [Popover](https://ngwr.dev/reference/components/popover) |
| --- | --- |

## See also

- [Line Chart](https://ngwr.dev/charts/line-chart) — One or more series of values as lines.
- [Bar Chart](https://ngwr.dev/charts/bar-chart) — Vertical bars for one series of values.
- [Calendar](https://ngwr.dev/reference/components/calendar) — A month calendar for picking a date or a date range.
- [Popover](https://ngwr.dev/reference/components/popover) — Show a template, or a text tooltip, next to its trigger.