Feature Request: Add Support for Clickable Links in State Diagram Nodes

[BambioGaming]

Proposal

Feature Request

Mermaid.js currently supports clickable links in flowcharts using the click directive:

graph TD
    A[Start] --> B[Go to Google]
    B --> C[End]
    click B "https://google.com" "Visit Google"

However, state diagrams do not support clickable links in the same way.
It would be very useful to have a similar feature for state diagrams, allowing nodes to link to external URLs or trigger JavaScript functions.

Use Case

Making state transition diagrams interactive for documentation, tutorials, and apps.

Example:

stateDiagram
    [*] --> Idle
    Idle --> Google
    Google --> [*]
    click Google "https://google.com" "Visit Google"

This should allow clicking Google to open https://google.com.

Proposed Solution

1. Introduce click directive support for state diagrams, just like flowcharts.
2. Support both URL links and JavaScript function calls.
3. Ensure accessibility and maintain SVG compatibility.

Related Discussions

#6304

Would love to hear thoughts on feasibility!

Example

No response

Screenshots

No response

[nour0205]

Hey @BambioGaming,

I looked into how the click directive is implemented in flowcharts and whether we can extend this functionality to state diagrams. Based on the findings, I fully support adding this feature, as it would enhance the interactivity of state diagrams in the same way it does for flowcharts.

Current click Functionality in Flowcharts

In flowcharts, click directives allow nodes to:

• Trigger a JavaScript callback function
• Open a URL in a new tab (_blank)
• Display an optional tooltip

Verified Implementation Details from the Codebase:

1. flowDb.ts

The setClickEvent() function registers clickable nodes, while setClickFun() processes arguments and attaches event listeners.

public setClickEvent(ids: string, functionName: string, functionArgs: string) {
    ids.split(',').forEach((id) => {
        this.setClickFun(id, functionName, functionArgs);
    });
    this.setClass(ids, 'clickable');
}

flowRenderer.ts

If a node contains a link (vertex.link), it wraps the node in an <a> tag.
This ensures clickable links work in SVG.

for (const vertex of data4Layout.nodes) {
    const node = select(`#${id} [id="${vertex.id}"]`);
    if (!node || !vertex.link) {
        continue;
    }
    const link = doc.createElementNS('http://www.w3.org/2000/svg', 'a');
    link.setAttributeNS('http://www.w3.org/2000/svg', 'class', vertex.cssClasses);
    link.setAttributeNS('http://www.w3.org/2000/svg', 'rel', 'noopener');
    if (securityLevel === 'sandbox') {
        link.setAttributeNS('http://www.w3.org/2000/svg', 'target', '_top');
    } else if (vertex.linkTarget) {
        link.setAttributeNS('http://www.w3.org/2000/svg', 'target', vertex.linkTarget);
    }
}

flow/parser.ts

The parser extracts click definitions and calls setClickEvent().

spyOn(flowDb, 'setClickEvent');
const res = flow.parser.parse('graph TD\nA-->B\nclick A "https://example.com" "Visit Example"');
expect(flowDb.setClickEvent).toHaveBeenCalledWith('A', 'https://example.com', 'Visit Example');

State Diagram Findings
After reviewing the state diagram files, I found that there is no existing support for click interactions

Proposed Implementation

1. Modify stateDb.ts

• Implement setClickEvent(id, functionName, functionArgs), similar to flowDb.ts.

2. Modify stateRenderer.ts

• Implement similar logic as flowRenderer.ts.
• Wrap state diagram nodes inside <a> elements if they contain a click event.

3. Modify state/parser.ts

• Add parsing logic for click <state> "<URL>" "<Tooltip>".

This feature would make state diagrams more interactive and useful Looking forward to feedback on feasibility.

[BambioGaming]

Hi @nour0205,

Thank you for your reply! I appreciate the clarification, and I'll start working on the issue right away. I'll keep you updated on my progress.

[BambioGaming]

Hi again @nour0205 👋

Quick update on my progress implementing clickable links in state diagram nodes:

So far, I’ve:

• Extended the parser (stateDiagram.jison) to support the click <id> "<url>" "<tooltip>" directive

• Updated StateDB to store the link data and expose it via getLinks()

• Ensured addLink() is triggered correctly during parsing

• Implemented and tested the clickable link wrapping logic in stateRenderer.js

However, it turns out that stateRenderer.js is not the one currently used for rendering state diagrams. Instead, stateRenderer-v3-unified.ts is being used.

I’m now trying to trace the rendering path inside stateRenderer-v3-unified.ts, but the actual node rendering logic appears to be abstracted away — I haven’t located where the <g> nodes are inserted yet to apply the clickable <a> wrapper cleanly.

Any guidance on where that happens in the unified renderer would be greatly appreciated 🙏

[BambioGaming]

Hi @nour0205 👋

I’ve successfully implemented support for the click directive in stateDiagram, including both URL and tooltip functionality, just like in flowchart.

Supported syntax:

click StateA "https://example.com" "Tooltip text"
click StateB href "https://docs.com"

I’ve opened a pull request here: #6423

Looking forward to feedback and happy to adjust anything needed!