Mermaid Timeline Syntax: Every Element Explained with Examples

# Mermaid Timeline Syntax: Every Element Explained with Examples

This is the definitive syntax reference for Mermaid timelines. Not a beginner's intro — a complete element-by-element breakdown of every syntax feature, with working examples and the edge cases you'll actually hit.

If you're new to timelines, start with the Mermaid Timeline Instructions Guide. Come back here when you need the specific syntax for something.

Diagram Declaration

Every Mermaid timeline starts with the timeline keyword on its own line:

timeline
    title My First Timeline
    Event 1 : Period 1
    Event 2 : Period 2

What this does: The simplest valid timeline — a title and two events. timeline is the type declaration. Without it, Mermaid doesn't know which diagram type you're writing.

Edge case: Timeline (capital T) does NOT work. The keyword is case-sensitive: timeline only.

---

Title Element

timeline
    title Product Roadmap 2026
    Launch MVP : Q1
    Beta program : Q2
    Public launch : Q3

Syntax: title Your Title Text

Rules:

- Goes immediately after the timeline declaration

- Optional — timelines render without a title

- One title only — multiple title lines cause parse errors

- No quotes needed, even with spaces

What this does: Adds a heading above the timeline. Recommended for any timeline that will be shared or embedded in docs — gives immediate context.

---

Event Syntax

The core building block:

timeline
    title Event Syntax Examples
    Single event : Period A
    Another event : Period B
    Third event : Period C

Syntax: EventLabel : TimePeriod

The colon : separates the event label from the time period. Both sides are plain text — no quoting needed unless you need special characters.

What this does: Three events mapped to three periods. The period (right of the colon) is what renders as the time label in the diagram.

Edge cases:

- Missing colon: the line is treated as a multi-event entry (see below), not a new event with a period

- Extra spaces around the colon are fine: Event : Period and Event:Period both work

- Long event labels: keep under 50 chars for clean rendering. Longer labels wrap or overflow.

---

Section Element

Sections group events into visual blocks:

timeline
    title Grouped by Phase
    section Phase 1
        Research complete
        Prototype built : Month 1
    section Phase 2
        User testing done
        Feedback analyzed : Month 2
    section Phase 3
        Final version shipped
        Documentation done : Month 3

Syntax: section Section Name

Rules:

- Sections must come before their events (events are indented under the section)

- A timeline can mix sections and non-section events — though it's cleaner to use one or the other

- Section names appear as visual dividers in the rendered diagram

- No end keyword needed — the next section or end of file closes the current one

What this does: Adds visual grouping. Three phases, each with two events. The section header acts like a category label for the events underneath.

---

Multi-Event Entries (Parallel Events)

Multiple events can share the same time period:

timeline
    title Parallel Work in Q1
    section January
        Backend API built
        Frontend prototype
        Mobile wireframes : January
    section February
        API integration
        Frontend polish
        Mobile beta build : February

Syntax: List multiple items under a section. Only the last item gets the : Period marker. The others are treated as additional events for the same period.

What this does: Shows three parallel work streams in each month. January has three simultaneous activities; February has three more. The time period only appears once (on the last item), preventing visual clutter.

Edge case: All items above the colon-marked one render as events for the same period. If you accidentally omit the colon from every item in a section, Mermaid may render them oddly — always have exactly one event : period per section as the anchor.

---

Date and Period Formats

Mermaid timelines are format-agnostic. The period text is just a label — Mermaid doesn't validate or parse dates:

timeline
    title Date Format Flexibility
    Project kick-off : 2026-01-01
    Sprint 1 ends : January 14
    Beta launch : Q1 2026
    Public launch : Spring 2026
    Year-end review : Dec 2026

What this does: Shows five different date/period formats in one diagram. ISO dates, natural language months, quarter notation, seasons, and abbreviated months — all valid. Pick the format that matches your audience's expectations.

Best practice: Be consistent within a single timeline. Mixing formats (ISO dates in section 1, "Q1/Q2" in section 2) looks unprofessional. Choose one convention and stick to it.

---

Theme Configuration

Apply Mermaid's built-in themes via the %%{init}%% directive:

%%{init: { 'theme': 'forest' } }%%
timeline
    title Forest Theme Timeline
    section 2024
        Planted seeds
        First growth : 2024
    section 2025
        Rapid expansion
        Maturity reached : 2025
    section 2026
        Full bloom : 2026

Syntax: %%{init: { 'theme': 'THEMENAME' } }%% on the line before timeline

Available themes: default, forest, dark, neutral, base

What this does: Applies the "forest" color theme to the entire diagram. The %%{init}%% directive tells the Mermaid renderer to apply these settings before rendering.

Note: The init directive affects the whole diagram. You can also set logLevel, fontFamily, and other renderer options in the same object.

---

Custom Styling via init

More advanced customization through the init block:

%%{init: {
  'theme': 'base',
  'themeVariables': {
    'primaryColor': '#7B2D8B',
    'primaryTextColor': '#fff',
    'lineColor': '#7B2D8B'
  }
} }%%
timeline
    title Custom Color Timeline
    Feature A shipped : Q1
    Feature B launched : Q2
    Feature C in beta : Q3
    Full suite complete : Q4

What this does: Sets custom colors using themeVariables. primaryColor changes the section/event block color. primaryTextColor sets text color inside blocks. lineColor sets the connecting line color. Use hex codes.

---

Section-Free Timelines

For simple linear sequences, skip sections entirely:

timeline
    title Simple Linear Timeline
    Idea formed : Week 1
    Research done : Week 2
    Prototype built : Week 4
    Tested with users : Week 6
    Shipped : Week 8

What this does: A clean 5-event linear timeline with no section grouping. Works best for short timelines (under 8 events) where the events are sequential and don't need categorization.

---

Long Labels and Wrapping

timeline
    title Labels of Different Lengths
    Short : Jan
    A medium-length event label here : Feb
    This is a much longer event label that will test wrapping behavior : Mar
    Back to short : Apr

What this does: Tests how labels of different lengths render. Short labels are clean. Medium labels work fine. Very long labels will wrap or overflow depending on the renderer. Rule of thumb: Keep event labels under 50 characters. If you need more context, put it in a supporting document and keep the timeline label concise.

---

Nesting Sections: What Works and What Doesn't

Mermaid timelines do NOT support nested sections. You can't do:

section Phase 1
  section Sub-phase 1a

This will either parse incorrectly or render as a section named "section Sub-phase 1a". If you need hierarchy, use a different diagram type:

- For hierarchical breakdowns: use a mindmap

- For task dependencies: use a Gantt chart

- For process hierarchy: use a flowchart

---

Complete Syntax Quick Reference

---

Common Parse Errors and Fixes

Error: "Diagram not rendered"

Usually means a typo in the timeline keyword, or the init directive is malformed.

Error: Events in wrong section

Check your indentation. Section events must be indented relative to the section keyword.

Diagram renders but missing events

A missing colon means the line was parsed as a multi-event item without a period anchor. Add : period to the event.

All events show same period

Every event in a section without its own colon inherits the last anchored period. Make sure each period group has exactly one : period marker.

---

Related Timeline Resources

- Mermaid Timeline Instructions: Full Guide — beginner-friendly walkthrough

- 10 Timeline Examples with Step-by-Step Code — real use cases

- Research Plan Timeline Examples — academic and UX research

---

Try this live in our free Mermaid Editor → mermaideditor.lol

Every syntax example on this page works in our editor. Test edge cases, experiment with themes, and export your finished timeline.

---

*Related: Mermaid Cheat Sheet · Diagram Templates · Home*