Add funnel diagram type

[floatingsidewal]

Proposal

Funnel charts are one of the most widely used business visualizations for sales pipelines, conversion rates, support throughput, and AARRR metrics—yet Mermaid currently lacks them.

Use Cases

Sales Pipeline Visualization
Instantly show conversion rates across stages (Visitors → Leads → MQLs → SQLs → Opportunities → Closed-Won) with drop-off percentages in READMEs, Notion pages, or sales reports — the #1 requested use case in the community.
Product & Growth Metrics (AARRR Funnels)
Track user onboarding, activation, and retention funnels (Sign-ups → Verified → First Action → Active User → Paying Customer) directly in markdown docs, wikis, or analytics dashboards without embedding images.
Customer Support & Operations Throughput
Visualize ticket or issue resolution funnels (Incoming Tickets → Assigned → In Progress → Resolved → Closed) to highlight bottlenecks in internal runbooks, Confluence pages, or incident post-mortems.

Screenshots

Marketing Funnel Example:

Scaled funnel shapes:

With stage notes:

Syntax

Example syntax option 1:

  # Simple - ID becomes the display label
  funnel
      stage1[100] --> stage2[50] --> stage3[25]

  # With custom labels - ID separate from display text
  funnel
      stage1["Stage 1 is awesome": 100] --> stage2["Stage 2": 50] --> stage3[25]

  # Notes reference by ID (unquoted)
  funnel
      stage1[100] --> stage2[50] --> stage3[25]

      note stage1 "Description of stage 1"
      note stage2 "Description of stage 2"

Example syntax option 2:

      funnel title Customer Journey
        "Awareness": 5000
        desc "Customer discovers the brand"
        desc "Through marketing channels"
        "Interest": 2000
        desc "Customer shows interest"
        desc "Engages with content"
        "Decision": 500
        desc "Customer makes purchase"

Example syntax option 3: (Scaled funnel)

      funnel showData trueScale
        title Revenue by Quarter (Proportional)
        "Q1": 2500000
        "Q2": 1800000
        "Q3": 900000
        "Q4": 450000

Implementation

I will try and implement it myself.

[shubhamparikh2704]

Hi @floatingsidewal , thanks for the proposal. For syntax Example syntax option 2 is looking good. But I suggest to check existing mermaid syntax and consider the syntax are more align with existing syntax. Once you finalised the syntax maybe you post here so we can discuss it before finalising.

[floatingsidewal]

Although, I also like the syntax option 2, when I took a look at the code today, syntax style 1 seems to align better with other diagram types. Associating "notes" with diagram elements is very straightforward and multi-line rendering.

A working example is located here:

I'd love to get some more comments on this before I formalize the PR.

[shubhamparikh2704]

Hi @floatingsidewal!

Thank you so much for this, and for your efforts in keeping the syntax aligned with Mermaid's conventions - that's really important to us and we genuinely appreciate the thought and work you've put into this.
We had a chance to discuss the syntax as a team today, and we think the syntax below might bring it even closer to our existing patterns. We'd love to hear your thoughts on this proposed approach!

---
config:
    theme: redux
    funnel:
        showData: true
        trueScale: true
title: "Revenue by Quarter (Proportional)"
---
funnel-beta
    stage1:
        size: 100
        label: "Customer discovers the brand" 
        note: This is a note 
    stage2:
        size: 50
        label: stage2 text
    "Label for Stage 3": 900000
    stage4: 450000
    
    classDef Pink color: #ffcccc
    class stage1 pink
    style stage2 color: #2196F3

[garcipat]

Isnt this very similar to a vertical sankey diagram?