# SmartVisuals Calendar Heatmap for Power BI

> Calendar heatmap for Power BI: year strips, month grid, weekday x hour punch card and matrix heatmap, fiscal and ISO weeks, offline holidays for 21 countries.

- Page: https://www.smartvisuals.io/visuals/calendar-heatmap
- Fields and settings: https://www.smartvisuals.io/visuals/calendar-heatmap/settings
- Microsoft Marketplace: https://marketplace.microsoft.com/en-us/product/smartvisuals.smartvisuals-calendar-heatmap?tab=overview
- Package: https://www.smartvisuals.io/downloads/smartvisuals-calendar-heatmap-1.0.0.0.pbiviz
- Sample report (zipped .pbip): https://www.smartvisuals.io/samples/smartvisuals-calendar-heatmap-sample-1.0.0.0.zip
- Price: Free tier for every viewer; premium $1.99 per user per month or $19 per user per year on Microsoft Marketplace, with a 30-day free trial. Premium works in edit mode without a licence; unlicensed viewers see the free tier, never a blocked visual.
- Certified by Microsoft: no
- Version: 1.0.0.0
- GUID (visualType and publicCustomVisuals): `calendarHeatmap23B3BA3C1DCD4DE5A9759C587CE879F3`

## What is free

- **Three views in one visual**: Year strip, month grid with click-to-zoom, and a matrix heatmap: weekday x hour, weekday x month, year x month, month x day, weekday x week, or any two fields. Readers can switch views with chips when View switcher for readers is on.
- **Business calendars**: Fiscal years with any start month, ISO or "1 January = week 1" week numbers, weeks starting Monday, Sunday or Saturday, and date hierarchies that work as-is.
- **Holidays for 21 countries, offline**: Public holidays computed from rules inside the visual, or your own holidays from a data column, hatched behind the days. Plus a today marker.
- **Rules, badges and pinned notes**: Up to 3 rules on the value (above, below, between, top or bottom N days) with star, flag, check, warning and other badges or a fill colour, named in the legend. Notes from your data or pinned in the format pane for a day or a date range.
- **KPI line, insight and margins**: Total, per day, best day, streak, one "vs target" and one "vs prior year" figure, a plain-language insight sentence, sparkline margins with weekday profile and weekly totals, and % of row, column or total in the matrix.
- **Four themes, ten palettes**: Rounded tiles, dark glow, editorial squares and dot matrix; linear, quantile, log and manual-threshold scales, diverging centres, smart range, colour-blind-safe viridis and cividis, and the report theme colour.
- **Native Power BI behaviour**: Cross-filtering, Ctrl multi-select, drill-through menu, report-page tooltips, keyboard navigation, high contrast and five languages (EN, CS, DE, ES, FR).

## What premium adds

- **Target attainment colouring**: Colour every day by attainment against a Target measure, so days above and below plan stand out at a glance.
- **Like-for-like year over year**: Colour every day by change versus the same weekday or the same date last year, with year-over-year change in the year headers.
- **Retail 4-4-5 calendars**: Retail 4-4-5, 4-5-4 and 5-4-4 fiscal years with 52/53 weeks and P1-P12 period labels.
- **Small multiples and measure switching**: One calendar per plant, team or product on shared or independent scales, and switching between measures in the format pane and for report readers.
- **Unusual-day detection**: Judges each weekday against its own normal and ignores holidays and shutdowns, so only the days that genuinely stand out are flagged.
- **Comparison rules**: Rules and badges on target, attainment %, change versus prior year or unusual days.

## Fields

| Field | Internal name | Takes | Needed | What it is for |
| --- | --- | --- | --- | --- |
| Date | `date` | Column | Optional, up to 4 | A date or date/time column. A date hierarchy works too — the visual rebuilds the days from its levels. |
| Value | `value` | Measure | Optional, up to 5 | What colours the cells. Add several measures to switch between them. Empty = count of rows. |
| Target | `target` | Measure | Optional | Optional goal per day — colour cells by attainment. |
| Small multiples | `group` | Column | Optional | One calendar per value (plant, team, product…). |
| Matrix rows | `rows` | Column | Optional | Row field for the matrix heatmap view. |
| Matrix columns | `columns` | Column | Optional | Column field for the matrix heatmap view. |
| Notes | `annotation` | Column | Optional | Event or note text per day — marked on the cell and shown in the tooltip. |
| Holidays | `holiday` | Column | Optional | Holiday name per day (your own calendar table). Built-in national packs are in the format pane. |
| Tooltips | `tooltips` | Measure | Optional, up to 10 | Extra measures shown in tooltips. |

## Format pane

Each card is a key under `visual.objects` in a PBIR visual.json; each setting is a property of it. Toggles take `true`/`false`, choices and text a value in single quotes (`'auto'`), numbers a `D` suffix (`12D`).

### View (`view`)

| Setting | Internal name | Type or options |
| --- | --- | --- |
| Type | `type` | `yearStrip` (Year strip), `monthGrid` (Month grid), `matrix` (Matrix heatmap) |
| Years | `years` | `auto` (Auto), `years` (One strip per year), `continuous` (Continuous) |
| Period | `period` | `all` (All data), `latestYear` (Latest year), `last12` (Last 12 months) |
| Show switcher | `showSwitcher` | On / off |
| Allow zoom | `allowZoom` | On / off |

### Calendar (`calendar`)

| Setting | Internal name | Type or options |
| --- | --- | --- |
| Week start | `weekStart` | `1` (Monday), `0` (Sunday), `6` (Saturday) |
| Year mode | `yearMode` | `calendar` (Calendar year), `fiscal` (Fiscal year), `retail` (Retail 4-4-5 year) |
| Fiscal start | `fiscalStart` | `0` (January), `1` (February), `2` (March), `3` (April), `4` (May), `5` (June), `6` (July), `7` (August), `8` (September), `9` (October), `10` (November), `11` (December) |
| Fiscal naming | `fiscalNaming` | `end` (By end year), `start` (By start year) |
| Retail pattern | `retailPattern` | `445` (4-4-5), `454` (4-5-4), `544` (5-4-4) |
| Retail end month | `retailEndMonth` | `0` (January), `1` (February), `2` (March), `3` (April), `4` (May), `5` (June), `6` (July), `7` (August), `8` (September), `9` (October), `10` (November), `11` (December) |
| Retail end weekday | `retailEndWeekday` | `0` (Sunday), `1` (Monday), `2` (Tuesday), `3` (Wednesday), `4` (Thursday), `5` (Friday), `6` (Saturday) |
| Retail rule | `retailRule` | `last` (Last weekday of month), `nearest` (Weekday nearest month end) |
| Week numbers | `weekNumbers` | `none` (Off), `iso` (ISO 8601), `simple` (Week of 1 January = 1) |
| Holidays | `holidays` | `none` (None), `us` (United States (federal)), `uk` (United Kingdom (England & Wales)), `de` (Germany (national)), `fr` (France), `cz` (Czechia), `pl` (Poland), `at` (Austria), `nl` (Netherlands), `es` (Spain (national)), `it` (Italy), `ca` (Canada (federal)), `au` (Australia (national)), `sk` (Slovakia), `hu` (Hungary), `be` (Belgium), `ie` (Ireland), `pt` (Portugal), `se` (Sweden), `dk` (Denmark), `no` (Norway), `fi` (Finland) |
| Shade weekends | `shadeWeekends` | On / off |
| Show today | `showToday` | On / off |
| Weekend color | `weekendColor` | Colour |
| Holiday color | `holidayColor` | Colour |
| Today color | `todayColor` | Colour |

### Colours (`colors`)

| Setting | Internal name | Type or options |
| --- | --- | --- |
| Palette | `palette` | `theme` (Theme), `report` (Report theme colour), `greens` (Greens (GitHub)), `blues` (Blues), `oranges` (Oranges), `purples` (Purples), `viridis` (Viridis (colour-blind safe)), `cividis` (Cividis (colour-blind safe)), `magma` (Magma), `redBlue` (Red – Blue (diverging)), `brownTeal` (Brown – Teal (diverging)), `purpleGreen` (Purple – Green (diverging)), `custom` (Custom colours) |
| Low color | `lowColor` | Colour |
| Mid color | `midColor` | Colour |
| High color | `highColor` | Colour |
| Empty color | `emptyColor` | Colour |
| Scale type | `scaleType` | `linear` (Linear), `quantile` (Quantile (outlier-proof)), `log` (Logarithmic), `thresholds` (Manual thresholds) |
| Steps | `steps` | Number |
| Diverging | `diverging` | On / off |
| Center | `center` | `zero` (Zero), `mean` (Mean), `median` (Median), `custom` (Custom value) |
| Center value | `centerValue` | Number |
| Thresholds | `thresholds` | Text |
| Domain min | `domainMin` | Text |
| Domain max | `domainMax` | Text |
| Clamp outliers | `clampOutliers` | On / off |
| Reverse | `reverse` | On / off |
| Aggregation | `aggregation` | `sum` (Sum), `avg` (Average), `min` (Minimum), `max` (Maximum), `count` (Count of rows) |

### Cells (`cells`)

| Setting | Internal name | Type or options |
| --- | --- | --- |
| Shape | `shape` | `theme` (Theme default), `rounded` (Rounded), `square` (Square), `circle` (Circle) |
| Gap | `gap` | Number |
| Show values | `showValues` | On / off |
| Show day numbers | `showDayNumbers` | On / off |

### Labels (`labels`)

| Setting | Internal name | Type or options |
| --- | --- | --- |
| Font family | `fontFamily` | `inter` (Inter), `segoe` (Segoe UI), `arial` (Arial), `georgia` (Georgia) |
| Font size | `fontSize` | Number |
| Font color | `fontColor` | Colour |
| Show month labels | `showMonthLabels` | On / off |
| Weekday labels | `weekdayLabels` | `alternate` (Alternate days), `all` (All days), `none` (Off) |
| Show year totals | `showYearTotals` | On / off |

### Legend (`legend`)

| Setting | Internal name | Type or options |
| --- | --- | --- |
| Prop_Show | `show` | On / off |
| Position | `position` | `bottom` (Bottom), `top` (Top) |
| Show title | `showTitle` | On / off |
| Show markers | `showMarkers` | On / off |

### Summary (`summary`)

| Setting | Internal name | Type or options |
| --- | --- | --- |
| Show | `show` | On / off |
| Show insights | `showInsights` | On / off |

### Sparkline margins (`margins`)

| Setting | Internal name | Type or options |
| --- | --- | --- |
| Weekday profile | `weekdayProfile` | On / off |
| Period totals | `periodTotals` | On / off |
| Bar color | `barColor` | Colour |

### Matrix (`matrix`)

| Setting | Internal name | Type or options |
| --- | --- | --- |
| Axes | `axes` | `auto` (Auto), `fields` (Rows × Columns fields), `weekdayHour` (Weekday × Hour), `weekdayMonth` (Weekday × Month), `monthYear` (Year × Month), `dayMonth` (Month × Day), `weekdayWeek` (Weekday × Week) |
| Row order | `rowOrder` | `data` (Natural order), `az` (A → Z), `totalDesc` (Largest total first) |
| Col order | `colOrder` | `data` (Natural order), `az` (A → Z), `totalDesc` (Largest total first) |
| Show as | `showAs` | `value` (Value), `pctRow` (% of row), `pctCol` (% of column), `pctTotal` (% of total) |
| Hour format | `hourFormat` | `24` (24-hour), `12` (12-hour) |

### Notes (`annotations`)

| Setting | Internal name | Type or options |
| --- | --- | --- |
| Prop_Show | `show` | On / off |
| Pinned | `pinned` | Text |
| Show text | `showText` | On / off |
| Prop_RuleColor | `color` | Colour |

### Comparison (`comparison`)

| Setting | Internal name | Type or options |
| --- | --- | --- |
| Mode | `mode` | `none` (Off), `target` (Versus target), `priorYear` (Versus prior year) |
| Alignment | `alignment` | `weekday` (Same weekday (52 weeks back)), `date` (Same date) |
| Range | `range` | Number |
| Show year deltas | `showYearDeltas` | On / off |

### Small multiples (`multiples`)

| Setting | Internal name | Type or options |
| --- | --- | --- |
| Columns | `columns` | Number |
| Shared scale | `sharedScale` | On / off |
| Show titles | `showTitles` | On / off |

### Insights (`insights`)

| Setting | Internal name | Type or options |
| --- | --- | --- |
| Anomalies | `anomalies` | On / off |
| Sensitivity | `sensitivity` | `low` (Low), `medium` (Medium), `high` (High) |
| Direction | `direction` | `both` (High and low), `high` (High only), `low` (Low only) |
| Streaks | `streaks` | On / off |
| Streak threshold | `streakThreshold` | Number |
| High color | `highColor` | Colour |
| Low color | `lowColor` | Colour |

### Measures (`measures`)

| Setting | Internal name | Type or options |
| --- | --- | --- |
| Active | `active` | Text |
| Show switcher | `showSwitcher` | On / off |

### Theme (`theme`)

| Setting | Internal name | Type or options |
| --- | --- | --- |
| Selected theme | `selectedTheme` | `smartvisuals` (SmartVisuals), `dark` (Dark), `clean` (Clean), `slate` (Slate) |
| Transparent bg | `transparentBg` | On / off |