← All Articles

Mermaid Gantt Chart: Examples & Best Practices

Create Gantt charts with Mermaid.js for project planning. Learn task syntax, dependencies, milestones, sections, and date formatting with practical examples.

Introduction to Mermaid Gantt Charts

Gantt charts visualize project schedules — showing tasks, durations, dependencies, and milestones on a timeline. While dedicated project management tools like Jira or MS Project offer interactive Gantt charts, Mermaid lets you create them as code that lives in your documentation.

This is perfect for README files, design docs, and technical proposals where you need a visual timeline without the overhead of a separate tool.

Basic Gantt Syntax

gantt
    title My Project Plan
    dateFormat YYYY-MM-DD

    section Planning
    Requirements gathering :a1, 2025-01-01, 7d
    System design          :a2, after a1, 5d

    section Development
    Backend implementation  :b1, after a2, 14d
    Frontend implementation :b2, after a2, 10d

    section Testing
    Integration testing     :c1, after b1, 5d
    UAT                     :c2, after c1, 3d
Try in Editor →

Key Elements

  • title — Chart title
  • dateFormat — How dates are parsed (YYYY-MM-DD is standard)
  • section — Groups related tasks
  • Tasks follow the format: Task name : id, start, duration

Task Definition Formats

Tasks can be defined in several ways:

gantt
    dateFormat YYYY-MM-DD

    section Various Formats
    Fixed dates       :t1, 2025-03-01, 2025-03-10
    With duration     :t2, 2025-03-01, 10d
    After dependency  :t3, after t1, 5d
    No ID needed      :2025-03-15, 7d
Try in Editor →

Duration Units

- d — days (most common)

- h — hours

- m — minutes

- w — weeks

Task States

Tasks can have different visual states:

gantt
    dateFormat YYYY-MM-DD

    section Task States
    Completed task    :done, t1, 2025-01-01, 5d
    Active task       :active, t2, after t1, 5d
    Future task       :t3, after t2, 5d
    Critical task     :crit, t4, after t3, 3d
    Critical & active :crit, active, t5, after t4, 3d
Try in Editor →
  • done — Shown as completed (usually gray)
  • active — Currently in progress (highlighted)
  • crit — Critical path (usually red)
  • These can be combined: crit, done or crit, active

Milestones

Mark key dates with zero-duration milestones:

gantt
    dateFormat YYYY-MM-DD

    section Sprint 1
    User stories          :s1, 2025-01-06, 10d
    Sprint 1 review       :milestone, m1, after s1, 0d

    section Sprint 2
    Development           :s2, after m1, 10d
    Sprint 2 review       :milestone, m2, after s2, 0d

    section Release
    Release prep          :r1, after m2, 3d
    Go live               :milestone, m3, after r1, 0d
Try in Editor →

Dependencies

Tasks can depend on one or more previous tasks:

gantt
    dateFormat YYYY-MM-DD

    section Backend
    API design        :api, 2025-02-01, 5d
    Database schema   :db, 2025-02-01, 3d
    API development   :apidev, after api db, 10d

    section Frontend
    UI mockups        :ui, 2025-02-01, 7d
    Frontend dev      :fedev, after ui apidev, 10d

    section QA
    Testing           :test, after fedev, 5d
Try in Editor →

Notice after api db — the task starts after BOTH api and db are complete.

Practical Example: Software Release Plan

gantt
    title Q1 2025 Release Plan
    dateFormat YYYY-MM-DD
    axisFormat %b %d

    section Discovery
    User research           :done, ur, 2025-01-06, 10d
    Competitive analysis    :done, ca, 2025-01-06, 7d
    Requirements doc        :done, rd, after ur ca, 5d
    Requirements sign-off   :milestone, done, ms1, after rd, 0d

    section Design
    Architecture design     :done, ad, after ms1, 7d
    UI/UX design            :active, ux, after ms1, 10d
    Design review           :milestone, ms2, after ad ux, 0d

    section Development
    Backend services        :be, after ms2, 15d
    Frontend application    :fe, after ms2, 15d
    API integration         :int, after be, 5d

    section Quality
    Unit testing            :ut, after be fe, 5d
    Integration testing     :it, after int ut, 5d
    Performance testing     :crit, pt, after it, 3d
    Security audit          :crit, sa, after it, 3d

    section Release
    Staging deployment      :stg, after pt sa, 2d
    UAT                     :uat, after stg, 5d
    Production deployment   :milestone, crit, prod, after uat, 0d
Try in Editor →

Date Formatting

Input Date Format

Control how Mermaid parses your dates:

gantt
    dateFormat DD-MM-YYYY
    task1 :01-03-2025, 10d
Try in Editor →

Common formats:

- YYYY-MM-DD — ISO standard (recommended)

- DD-MM-YYYY — European

- MM-DD-YYYY — US

Axis Display Format

Control how the timeline axis looks:

gantt
    dateFormat YYYY-MM-DD
    axisFormat %Y-%m-%d

    section Tasks
    Task 1 :2025-01-01, 30d
Try in Editor →

Common axis formats:

- %Y-%m-%d — 2025-01-15

- %b %d — Jan 15

- %d/%m — 15/01

- %B %Y — January 2025

Excluding Dates

Skip weekends or holidays:

gantt
    dateFormat YYYY-MM-DD
    excludes weekends

    section Development
    Task 1 :t1, 2025-03-03, 5d
    Task 2 :t2, after t1, 5d
Try in Editor →

With weekends excluded, a 5-day task truly means 5 business days.

You can also exclude specific dates:

excludes weekends, 2025-12-25, 2025-12-26

Sections as Swim Lanes

Use sections to organize by team, phase, or component:

gantt
    title Cross-Team Project
    dateFormat YYYY-MM-DD

    section Team Alpha
    Feature A    :a1, 2025-03-01, 14d
    Feature B    :a2, after a1, 7d

    section Team Beta
    Feature C    :b1, 2025-03-01, 10d
    Feature D    :b2, after b1, 10d

    section Team Gamma
    Feature E    :g1, 2025-03-08, 14d
    Integration  :g2, after a2 b2 g1, 5d
Try in Editor →

Best Practices

  1. Use ISO date format (YYYY-MM-DD) — it's unambiguous and sorts correctly.
  1. Give tasks meaningful IDs — api_design is clearer than a1 when reading dependencies.
  1. Mark the critical path — use crit on tasks that directly impact the delivery date.
  1. Use milestones for key dates — they provide clear visual checkpoints.
  1. Exclude weekends with excludes weekends for realistic business-day planning.
  1. Keep sections logical — group by team, phase, or component. Don't mix organizational patterns.
  1. Update the done/active states as work progresses — this makes the chart a living document.
  1. Add axisFormat to make the timeline readable. %b %d (Jan 15) is usually the best balance of information and space.

Limitations

- Mermaid Gantt charts are read-only — you can't drag tasks or interact with them.

- Complex projects with hundreds of tasks are better served by dedicated PM tools.

- Resource assignment and workload balancing aren't supported.

- The layout engine may struggle with many overlapping dependencies.

Mermaid Gantt charts shine for documentation — embedding a project timeline in a README, proposal, or design doc where the audience needs to understand the plan but doesn't need to interact with it.

Conclusion

Mermaid Gantt charts turn project timelines into maintainable code. They're perfect for technical documentation, sprint planning overviews, and release plans that live alongside your source code. Start simple with sections and tasks, then add dependencies, milestones, and critical path markers as your planning matures.

Try it now in our free Mermaid Live Editor →

Try it now in our free Mermaid Live Editor →
← All Articles