> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://katalyz.crisp.help/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# Timeline widget

The **Timeline** widget is a **Gantt-style horizontal chart** for scheduling a deal. It combines three types of items on the same time axis: **phases**, **steps**, and **milestones**. Unlike the Steps widget (which is a pure action-plan list), Timeline is time-anchored — dates drive position, width, and ordering.

![](https://storage.crisp.chat/users/helpdesk/website/-/5/5/4/8/554891f22af0b400/screenshot-2026-06-17-at-11532_ej0gjj.png =764xauto)

## How to add

1. On the **floating build bar** at the bottom of the editor, locate the widget — in the primary widgets row, or under the **⌄ All widgets** popover if it's not there.
2. Drag the **Timeline** widget onto the target section.
3. Use the in-widget toolbar to **Add a phase** or **Add a milestone**; any steps you've created elsewhere in the room (in a Steps widget or directly in an action) will show up automatically if they have dates.

## The selection pill — Timeline controls

Click the Timeline to select it. The pill is minimal — most editing happens in the widget's own toolbar (range, today, fit, filter, add phase, add milestone):

1. **🌙 Dark mode** — flips the widget's surface to a dark treatment.
2. **Design** (paintbrush icon) — opens the contextual Design panel.
3. **⋮ More** — **Duplicate** · **Delete**.

1. **🌙 Mode sombre** — bascule la surface du widget vers un traitement sombre.
2. **Design** (icône pinceau) — ouvre le Panneau Design contextuel.
3. **⋮ Plus** — **Dupliquer** · **Supprimer**.
![](https://storage.crisp.chat/users/helpdesk/website/-/5/5/4/8/554891f22af0b400/screenshot-2026-06-17-at-15411_9csngp.png =1040xauto)

> **Steps and tasks shown on the Timeline are the same ones used elsewhere in the room.** There is a single underlying action plan — Timeline is another view of those same steps/tasks. Edit in either widget and the other updates immediately. Timeline adds its own **phases** and **milestones** on top — those are Timeline-specific.

> **Note:** clicking a step bar opens the same **action details sidepanel** used by the Steps widget (same 5 statuses, attributes, guidelines, comments, etc.).

## Three item types

| Item type | What it is | Display |
|---|---|---|
| **Phase**                | A broad time band (e.g. "Discovery", "Implementation", "Rollout") | Semi-transparent colored band spanning the date range, behind the steps |
| **Step**                | A scheduled action (same step data used elsewhere in the room) | A colored bar whose position = start date and width = due date − start date. Can contain tasks, shown in collapsed/expanded sub-rows. |
| **Milestone**                | A single-point event (e.g. "Contract signed", "Kickoff") | A flag marker above the grid at a specific date |

## What drives the visual

- **Start date & due date** → bar **position** and **width** on the time axis
- **Step bar color** → comes from the **palette set in the room's design/branding settings** so it matches your brand. (Status is still shown — via the status icon on the bar — but it does **not** change the color.)
- **Phase color** → picked from a predefined palette when you create the phase (purple, accent, teal, success, warning)
- **Tasks completion** → a **"completed / total"** progress badge on the step's label

## The Timeline toolbar

- **Range dropdown** — zoom level: **1w / 2w / 1m / 3m / 6m / 1y**. Controls the density of the time axis and how much of the deal you see on screen.
- **Today** — scrolls the view so **today's date lands in the middle** of the visible window, keeping the current zoom level. Use it to jump back to "now" after panning around.
- **Fit** — **auto-zooms and scrolls** so that all phases, milestones, and steps fit in the visible window. Picks a range that matches the total date span. Handy for a quick overview after adding or moving items.
- **Nav arrows** — scroll the view left/right in chunks (the chunk size adapts to the range — a few days on 1w, weeks on 3m, months on 1y).
- **Filter** (edit mode only) — two ways to narrow what's shown:
  - **By action** — one checkbox per step, so you can hide individual steps by name
  - **By status** — one checkbox per status (Not started / In progress / At risk / On hold / Completed), so you can hide entire status groups (e.g. hide everything Completed to focus on active work)
- **+ Add Phase** — popover to create a new phase (name + start + end, absolute or relative)
- **+ Add Milestone** — popover to create a new milestone (name + single date)

## Interactions on the chart

- **Click a step bar** — opens the same **action details sidepanel** used by the Steps widget (full attribute editor, guidelines, comments, attach email, etc. — see [Steps widget](https://katalyz.crisp.help/en/article/steps-widget-jd7fe5/))
- **Drag a step bar** — reschedules the step. Drag the body to shift start + due together; drag the start or due edge to resize.
- **Expand a step ("Show tasks")** — reveals task sub-rows under the step with their own dates
- **Double-click a phase or milestone label** — inline-edit popover for name / dates

> **Drag is disabled for relative dates.** When a step's (or phase's, or milestone's) date is **relative** to another action, its value is computed — so the bar can't be dragged. To reschedule it, either change the **reference action's** date (which cascades) or convert the date back to **absolute** in the sidepanel.

## Items without a date

- Steps, phases, or milestones that don't have both a start and due date (or a resolvable relative spec) are **not rendered on the chart**.
- They appear in an **"Unresolved dates" badge** on the toolbar — click the badge to see the list and add dates inline.
- This keeps the chart clean while still making unscheduled items visible and easy to fix.

## Relative dates

Step, phase, and milestone dates can be set as **absolute** (e.g. Mar 15) or **relative** to another action's date (e.g. "2 business days after Step 3's completion"). Useful for re-using a template where moving the kickoff shifts everything else.

If a relative date can't be resolved (the referenced action has no date, or was deleted), the item is marked unresolved and shows up in the **Unresolved dates** badge.

For the full breakdown — references, offsets, units, propagation — see [Relative dates for steps, phases & milestones](https://katalyz.crisp.help/en/article/relative-dates-for-steps-phases-milestones-196bhjc/).

## Timeline vs. Steps

- **Steps widget** — buyer-friendly action-plan list; great for detail, status, assignees, nested tasks, comments
- **Timeline widget** — scheduling view; great for "when" questions, dependencies, Gantt-style storytelling

Many teams use both: a Steps widget for the working action plan and a Timeline for the at-a-glance schedule narrative.

## Best practices

- **Use real dates**, not vague "Week 1 / Week 2" — specificity signals seriousness
- **Phase your timeline** — 2–4 phases group steps visually and help the buyer zoom out
- **Use milestones sparingly** — reserve them for truly pivotal events (kickoff, signature, go-live)
- **Lean on relative dates** when re-using a Timeline across deals — move the kickoff and everything else follows

## Related articles
- [Steps widget](https://katalyz.crisp.help/en/article/steps-widget-jd7fe5/)
- [Controlling visibility — pages, sections, actions, messages & guidelines](https://katalyz.crisp.help/en/article/controlling-visibility-pages-sections-actions-messages-guidelines-vc7vb1/)
- [Introduction to widgets](https://katalyz.crisp.help/en/article/introduction-to-widgets-skwh2f/)