Add labels on sankey links

[wf-r]

Add permanent text labels to Sankey links

What

Adds persistent, always-visible text labels to Sankey links, analogous to the existing node
labels. Five new attributes under link:

Attribute	Type	Description
link.textinfo	flaglist: "label", "value", "none"	Which information to show permanently on links
link.texttemplate	string / arrayOk	Template string, overrides textinfo when set
link.textfont	font	Font for link labels
link.valueformat	string	d3 format string for the value component
link.valuesuffix	string	Unit suffix appended to the formatted value

Why

Link information is currently hover-only, making Sankey diagrams unsuitable for static export
(PNG/SVG/print) wherever flow values or names need to be visible at all times. There is
long-standing community interest in this — see #4746.

External SVG overlays (the current workaround) are fragile: they break on node drags, require
timing hacks after layout transitions, and are excluded from toImage export. Native labels
solve all three problems.

How

Labels are rendered as real SVG <text> elements inside the .sankey group, immediately after
the link paths. This means:

• The existing group-level orientation transform applies automatically — labels stay upright in
  h and v layouts with no extra handling.
• Labels follow node drags via the existing updateShapes hook — no separate drag listener
  needed.
• Labels are included in toImage/PNG/SVG export — no overlay required.
  For circular (backward) links the label anchor reuses the same circularPathData midpoint as
  the hover label, so the position is consistent. Vertical centering on the anchor uses
  dominant-baseline="central".

Template rendering follows the established funnel/pie pattern via Lib.texttemplateString.
Available template variables: %{label}, %{value}, %{valueLabel} (formatted value +
suffix), %{source}, %{target}, %{customdata}.

Backward compatibility

Fully backward compatible. All new attributes default to textinfo: 'none' / texttemplate: '',
so existing figures render identically. No existing tests or baselines are affected.

Related

• Closes / addresses add optional text on Sankey links #4746 (add optional text on Sankey links)

[wf-r]

If you are interested in this please let me know. #7870 was just merged into v4.0, and would need some rework here to incorporate correct positioning.

[camdecoster]

@wf-r go for it. You'll need to change the target branch to v4.0.

[wf-r]

You'll need to change the target branch to v4.0.

I think I am not allowed to do it (or I don't find the option). Can you do this, please?

[wf-r]

Please have a look at this.

[wf-r]

I'm done for today. Things one could discuss:

• new attribute link.valueformat only applies to permanent link labels, not to link hovers (trace.valueformat does all the rest).
• link.textfont again only applies to permanent link labels, trace.textfont to everything else
• labels do currently not fade out. should they?

[camdecoster]

• Do you need the new attributes if there are already trace.valueformat and trace.textfont?
• What would the labels fading out look like?

[wf-r]

I'm back, sorry I was busy with other work.

• Do you need the new attributes if there are already trace.valueformat and trace.textfont?

You are right, link.valueformat could be removed in favor of trace.valueformat (which is already used for link and node hovers). As for link.textfont: Would we like to style labels different from nodes or node hovers? If not we could remove it and use trace.textfont. There are some plots that use different textfonts for different components (treemap), I have no preference how to do it here.

• What would the labels fading out look like?

Sankey nodes and links do a

....exit()
        .transition()
        .ease(c.ease).duration(c.duration)
        .style('opacity', 0)
        .remove();

while the link label just does sankeyLinkLabel.exit().remove();.

So if we e.g. filter links we get a slightly different behaviour between link label and link itself.