# SmartVisuals Timeline for Power BI

> Power BI timeline visual: events, ranges, milestones and swimlanes on one time axis with labels that never overlap. Zoom, icons, historic dates, keyboard.

- Page: https://www.smartvisuals.io/visuals/timeline
- Fields and settings: https://www.smartvisuals.io/visuals/timeline/settings
- Microsoft Marketplace: https://marketplace.microsoft.com/en-us/product/smartvisuals.smartvisuals-timeline?tab=overview
- Package: https://www.smartvisuals.io/downloads/smartvisuals-timeline-1.0.0.0.pbiviz
- Sample report (zipped .pbip): https://www.smartvisuals.io/samples/smartvisuals-timeline-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): `smartvisualsTimelineA7E4E5921C9F483E91463BA7B778AB45`

## What is free

- **Collision-free labels and markers**: Labels stack above and below each line, most important first, and no stem runs through another label. Markers that would touch stack apart. Hidden labels are counted in the status strip and come back as you zoom.
- **Points and ranges in one table**: End is optional: blank makes a point, a later date a range. An End of ongoing, or a date in the year 9999, draws a range that runs to today.
- **Milestones from the category name**: A category named Milestone draws diamonds with guide lines through every lane, recognised in 20 languages and overridable per category under Category Styles.
- **Dates, times and historic years**: Dates, date-times down to the minute, or whole-number years where negative years are BC. Write c. 1450 for an approximate date.
- **Icons, images and links**: Built-in icons such as flag, star, rocket, check, alert, team and trophy, and embedded data:image values. A Link column makes labels clickable; Power BI asks before the report is left. Web image addresses are never loaded.
- **Zoom, pan, overview and time-range selection**: Ctrl + mouse wheel or the buttons zoom, drag pans, the overview strip steers. Shift + drag selects a time range and filters the rest of the report. Open the report on the period you choose.
- **Reference lines, today line and descriptions**: Up to three labelled reference lines for deadlines and go-lives, a today line, descriptions drawn under the labels, and a two-row axis from minutes to millennia.
- **Four themes and conditional formatting (fx)**: SmartVisuals, Dark, Clean and Slate change the character of markers, bars, lanes and stems, not just the colours. Conditional formatting (fx) on event colours, a Legend, Comfortable or Compact density.
- **Built for reports**: Cross-filtering, cross-highlighting, report-page tooltips and the context menu.
- **Accessibility and 20 languages**: One tab stop, arrow keys through events and lanes, plus and minus zoom, a screen-reader name for every event, Windows high contrast, an Accessibility card and 20 interface languages.
- **Up to three swimlanes, horizontal layout**: Everything above, in up to three swimlanes in the horizontal layout, with no time limit.

## What premium adds

- **Any number of swimlanes and lane groups**: More than three lanes, and lane groups (Group > Lane) the reader can collapse: plant, workstream, team.
- **Background eras and the vertical layout**: Eras from a category named Era, Phase or Period, drawn as bands behind the lanes, and a vertical layout for long histories.
- **Milestone Dates**: Bind several date columns, one row per project and one column per milestone, and each becomes a named milestone on its project's line. No unpivoting.
- **Planned vs actual**: A ghost marker at the plan and the slip in days on every milestone, also per milestone column with each plan matched to its milestone by name. Pending and overdue milestones are flagged and counted first.
- **Story mode**: Step or play through the events, each one zoomed to and explained in a card.
- **Gap analysis**: Days between consecutive events per lane, with the longest quiet period marked.
- **Axis breaks**: Collapse empty centuries or quiet years so the busy part of the timeline gets the room.

## Fields

| Field | Internal name | Takes | Needed | What it is for |
| --- | --- | --- | --- | --- |
| Event | `event` | Column | Optional | What happened: the label of each event, milestone, range or era. |
| Start | `start` | Column | Optional | When it happens or begins. A date, a date and time, or a whole number read as a year (negative = BC); text such as c. 1450 marks an approximate date. Bind the field, not its Date Hierarchy. |
| End (Optional) | `end` | Column | Optional | When it ends. Blank or equal to Start makes a point in time; later makes a range; ongoing (or a date in the year 9999) runs to today. |
| Lane (Optional) | `lane` | Column | Optional | One swimlane per value: team, workstream, region, product line. Up to 3 lanes are free; more lanes are premium. |
| Lane Group (Premium) | `laneGroup` | Column | Optional | Puts lanes under a heading the reader can collapse (Group > Lane): plant > workstream, region > team. |
| Category (Optional) | `category` | Column | Optional | Colour, shape and legend. A category named Milestone draws milestones; Era, Phase or Period draws background eras (premium). |
| Description (Optional) | `description` | Column | Optional | Detail text shown in the tooltip, read by screen readers and shown in story mode. |
| Icon or Image (Optional) | `image` | Column | Optional | A built-in icon name (flag, star, rocket, check, ...) or an embedded data:image value. Web addresses are not loaded. |
| Link (Optional) | `link` | Column | Optional | A web address (https://...) the event opens when its label is clicked; Power BI asks the reader before leaving the report. |
| Milestone Dates (Premium) | `milestoneDates` | Column | Optional, up to 12 | Several date fields, one row per project: each field becomes a named milestone on the row's own line. No unpivoting. |
| Planned Date (Premium) | `planned` | Column | Optional | The planned date of the event: draws the slip between plan and actual. A planned date without a Start is a pending milestone, overdue once the date has passed. |
| Planned Milestone Dates (Premium) | `plannedMilestoneDates` | Column | Optional, up to 12 | The planned date of each Milestone Dates field, matched by name (Launch and Launch Planned) or else by order: slip, pending and overdue for every milestone. |
| Importance (Optional) | `importance` | Measure | Optional | Higher values keep their labels when space is short. Also carries cross-highlighting. |
| Tooltips | `tooltips` | Measure | Optional, up to 10 | Extra values shown in the tooltip. |

## 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`).

### Theme (`theme`)

| Setting | Internal name | Type or options |
| --- | --- | --- |
| Theme | `selectedTheme` | `smartvisuals` (SmartVisuals), `dark` (Dark), `clean` (Clean (White)), `slate` (Slate) |
| Background (empty = theme) | `bgColor` | Colour |
| Transparent Background | `transparentBg` | On / off |

### Layout (`layout`)

| Setting | Internal name | Type or options |
| --- | --- | --- |
| Orientation | `orientation` | `horizontal` (Horizontal), `vertical` (Vertical (Premium)) |
| Density | `density` | `comfortable` (Comfortable), `compact` (Compact) |
| Label Placement | `placement` | `alternate` (Alternate above and below), `above` (Above), `below` (Below) |
| Max Label Rows per Side (0 = Auto) | `maxLevels` | Number |
| Lane Order | `laneOrder` | `data` (Data order), `alpha` (Alphabetical), `start` (First event) |
| Lane Headers | `showLaneHeaders` | On / off |
| Lane Groups Start Collapsed (Premium) | `groupsCollapsed` | On / off |
| Range Labels | `showSpanLabels` | On / off |
| Dates in Labels | `showDatesInLabels` | On / off |
| Descriptions on the Canvas | `showDescriptions` | On / off |

### Time Axis (`axis`)

| Setting | Internal name | Type or options |
| --- | --- | --- |
| Show Axis | `show` | On / off |
| Position | `position` | `top` (Top), `bottom` (Bottom) |
| Two-Row Axis | `twoRows` | On / off |
| Gridlines | `gridlines` | On / off |
| Font Size | `fontSize` | Number |
| Font Colour (empty = theme) | `fontColor` | Colour |

### Events (`events`)

| Setting | Internal name | Type or options |
| --- | --- | --- |
| Marker Size | `markerSize` | Number |
| Milestone Guide Lines | `milestoneLines` | On / off |

### Colours (`dataColors`)

| Setting | Internal name | Type or options |
| --- | --- | --- |
| Colour | `fill` | Colour |

### Category Styles (`categoryStyles`)

| Setting | Internal name | Type or options |
| --- | --- | --- |
| Style | `style` | `auto` (Auto (from the name)), `marker` (Marker), `milestone` (Milestone), `bar` (Bar), `era` (Era band) |

### Eras (Premium) (`eras`)

| Setting | Internal name | Type or options |
| --- | --- | --- |
| Show Eras | `show` | On / off |
| Band Opacity % | `opacity` | Number |

### Today (`today`)

| Setting | Internal name | Type or options |
| --- | --- | --- |
| Show Today Line | `show` | On / off |
| Colour (empty = theme) | `lineColor` | Colour |

### Reference Lines (`referenceLines`)

| Setting | Internal name | Type or options |
| --- | --- | --- |
| Show Reference Lines | `show` | On / off |
| Line Style | `lineStyle` | `dashed` (Dashed), `solid` (Solid), `dotted` (Dotted) |
| Line 1 Date (YYYY-MM-DD or year) | `date1` | Text |
| Line 1 Label | `label1` | Text |
| Line 1 Colour (empty = theme) | `color1` | Colour |
| Line 2 Date (YYYY-MM-DD or year) | `date2` | Text |
| Line 2 Label | `label2` | Text |
| Line 2 Colour (empty = theme) | `color2` | Colour |
| Line 3 Date (YYYY-MM-DD or year) | `date3` | Text |
| Line 3 Label | `label3` | Text |
| Line 3 Colour (empty = theme) | `color3` | Colour |

### Legend (`legend`)

| Setting | Internal name | Type or options |
| --- | --- | --- |
| Show Legend | `show` | On / off |
| Position | `position` | `top` (Top), `bottom` (Bottom) |
| Font Size | `fontSize` | Number |
| Font Colour (empty = theme) | `fontColor` | Colour |

### Text (`labels`)

| Setting | Internal name | Type or options |
| --- | --- | --- |
| Font | `fontFamily` | `inter` (Inter), `segoe` (Segoe UI), `arial` (Arial), `georgia` (Georgia) |
| Font Size | `fontSize` | Number |
| Font Colour (empty = theme) | `fontColor` | Colour |
| Lane Header Size | `laneHeaderSize` | Number |

### Zoom & Navigation (`navigation`)

| Setting | Internal name | Type or options |
| --- | --- | --- |
| Zoom Buttons | `zoomButtons` | On / off |
| Overview Strip | `overview` | `auto` (When zoomed in), `always` (Always), `off` (Off) |
| Initial Window | `initialWindow` | `fit` (Fit all), `today` (Around today), `custom` (Custom range) |
| Months Around Today | `monthsAroundToday` | Number |
| From (YYYY-MM-DD or year) | `windowFrom` | Text |
| To (YYYY-MM-DD or year) | `windowTo` | Text |

### Story Mode (Premium) (`story`)

| Setting | Internal name | Type or options |
| --- | --- | --- |
| Story Mode Button | `enabled` | On / off |
| Seconds per Step (Play) | `seconds` | Number |

### Roadmap Analysis (Premium) (`analysis`)

| Setting | Internal name | Type or options |
| --- | --- | --- |
| Planned vs Actual | `showSlip` | On / off |
| On-Time Tolerance (Days) | `slipTolerance` | Number |
| Gap Between Events | `gapChips` | On / off |
| Mark Longest Quiet Period | `longestGap` | On / off |
| Collapse Empty Stretches | `axisBreaks` | On / off |
| Collapse Gaps Longer Than % of Span | `breakThreshold` | Number |

### Status Strip (`statusStrip`)

| Setting | Internal name | Type or options |
| --- | --- | --- |
| Show Status Strip | `show` | On / off |

### Accessibility (`accessibility`)

| Setting | Internal name | Type or options |
| --- | --- | --- |
| Focus Outline Colour | `focusColor` | Colour |
| Focus Outline Width | `focusWidth` | Number |
| Minimum Text Size | `minTextSize` | Number |
| Distinct Shape per Category | `distinctShapes` | On / off |