Making edge labels readable in Mermaid diagrams

Recently, I've been working to improve the way this website renders Mermaid diagrams. There are two things that I wanted to improve:

1. Edge labels have no horizontal padding, which makes them hard to read.
2. Switching between light and dark themes on the site doesn't trigger a re-render of the diagrams, so they don't change colors when the theme changes. (Post incoming ✍️)

These problems bugged me enough that I decided to document how I solved them. In this post, we'll tackle the first problem: styling edge labels in Mermaid diagrams.

The problem

Mermaid diagrams are rendered using SVG, which means that they are styled using CSS. However, the default styles for edge labels in Mermaid diagrams don't include any horizontal padding. This makes them look cramped and hard to read.

I mean, look at this diagram I'm building about reading SQL EXPLAIN plans:

The nodes in the diagram (the big off-white boxes) look so great, but look at the edge labels! They're a single pixel away from running off the edge of the label!

Booooooooo, default styles 👎

Better styles

Turns out, after some tinkering with the CSS in the developer tools, the solution is pretty simple. We just need one set of rules in our globals.css file:

/* 1. Target the foreignObject (the parent) */
foreignObject {
  display: flex;
  align-items: center;
  justify-content: center;

  /* 2. All items have a foreignObject */
  /* We only care about edgeLabels */
  &:has(.edgeLabel) {
    background-color: transparent;

    /* 3. Make the label transparent because, by default, */
    /* it has a translucent background color */
    .edgeLabel,
    .labelBkg {
      background-color: transparent !important;
    }

    /* 4. Now, changes to the paragraph */
    /* directly impact what you see */
    p {
      margin-inline: auto !important;
      max-width: max-content;
      border-radius: 8px;
      padding: 0 0.75rem;
    }
  }
}

This CSS does a few things:

• It makes the foreignObject display as a flex container, which allows us to center the edge labels while forcing the foreignObject to take up the max width.
• It targets the foreignObject, .edgeLabel, and labelBkg elements that contain an edge label and makes them transparent. This prevents the default translucent background color from showing up.
• It applies some styles to the p element inside the edge label, including horizontal padding and a border radius.

And with just those few lines of CSS, our diagram looks much better ✨:

---
title: How to read a SQL EXPLAIN plan
---
flowchart TD
  A{"Is there a child node we have not yet visited?"}
  A -->|Yes| B("Move to the child node and start from the beginning")
  A -->|No| C("This is the next step in the plan")
  C -->|It works with arbitrarily long text too!| D("Placeholder")

Now the edge labels are much more readable, and fit the general style of the rest of the diagram. The best part is that you can easily adjust the styles in the paragraph to customize the look.

sequenceDiagram
  participant A as Alice
  participant B as Bob
  A->>B: Hello Bob, how are you?
  B->>A: I'm good, thanks! How about you?
  A->>B: I'm doing well, just working on some Mermaid diagrams.
  B->>A: That sounds interesting! What are you working on?

    gitGraph
       commit
       commit
       branch develop
       commit
       commit
       commit
       checkout main
       commit
       commit

gantt
dateFormat  YYYY-MM-DD
title Adding GANTT diagram to mermaid
excludes weekdays 2014-01-10

section A section
Completed task            :done,    des1, 2014-01-06,2014-01-08
Active task               :active,  des2, 2014-01-09, 3d
Future task               :         des3, after des2, 5d
Future task2               :         des4, after des3, 5d

classDiagram
Class01 <|-- AveryLongClass : Cool
Class03 *-- Class04
Class05 o-- Class06
Class07 .. Class08
Class09 --> C2 : Where am i?
Class09 --* C3
Class09 --|> Class07
Class07 : equals()
Class07 : Object[] elementData
Class01 : size()
Class01 : int chimp
Class01 : int gorilla
Class08 <--> C2: Cool label

quadrantChart
    title Reach and engagement of campaigns
    x-axis Low Reach --> High Reach
    y-axis Low Engagement --> High Engagement
    quadrant-1 We should expand
    quadrant-2 Need to promote
    quadrant-3 Re-evaluate
    quadrant-4 May be improved
    Campaign A: [0.3, 0.6]
    Campaign B: [0.45, 0.23]
    Campaign C: [0.57, 0.69]
    Campaign D: [0.78, 0.34]
    Campaign E: [0.40, 0.34]
    Campaign F: [0.35, 0.78]