Skip to content

Add labels on sankey links - #7888

Open
wf-r wants to merge 14 commits into
plotly:mainfrom
wf-r:text_on_sankey_links
Open

wf-r wants to merge 14 commits into
plotly:mainfrom
wf-r:text_on_sankey_links

Conversation

@wf-r

@wf-r wf-r commented Jul 3, 2026

Copy link
Copy Markdown

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

@wf-r

wf-r commented Jul 25, 2026

Copy link
Copy Markdown
Author

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

camdecoster commented Jul 25, 2026 •

Copy link
Copy Markdown
Contributor

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

@wf-r
wf-r marked this pull request as draft July 27, 2026 07:13
@wf-r

wf-r commented Jul 27, 2026

Copy link
Copy Markdown
Author

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
wf-r marked this pull request as ready for review July 27, 2026 08:09
@wf-r

wf-r commented Jul 27, 2026

Copy link
Copy Markdown
Author

Please have a look at this.

…ominant-baseline, use block-shift like node labels), thread _d3locale/_meta/fallback through texttemplateString, and dedupe the orientation counter-transform into a shared uprightTransform helper.Also make opted-out traces free of per-link work by short-circuiting linkTextGetter to null.
@wf-r

wf-r commented Jul 27, 2026 •

Copy link
Copy Markdown
Author

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?

… group (fixes z-order with entering link paths), thread the label selection through updateShapes/attachDragHandler/startForce instead of DOM-querying every drag frame, and build each link's model once via a shared linkModels cache instead of duplicating it for paths and labels; exiting labels now fade out like links, and per-link texttemplate lookups use pointNumber instead of the loop index. Also switch link.texttemplate to the shared texttemplateAttrs() helper for a standard description and %{meta} support. More details in draftlog.
@camdecoster
camdecoster changed the base branch from master to v4.0 July 27, 2026 15:17
@camdecoster

Copy link
Copy Markdown
Contributor
  • 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

wf-r commented Aug 6, 2026 •

Copy link
Copy Markdown
Author

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.

@robertclaus robertclaus assigned camdecoster and unassigned emilykl Aug 6, 2026
@robertclaus
robertclaus requested review from camdecoster and removed request for emilykl August 6, 2026 19:59
@camdecoster
camdecoster deleted the branch plotly:main August 24, 2026 18:46
@camdecoster

Copy link
Copy Markdown
Contributor

This got closed by accident! I still want to get the work merged, but the v4.0 branch got deleted and now I can't change the base branch of the PR. I'll see if there's another way to get this open again.

@camdecoster camdecoster reopened this Aug 25, 2026
@camdecoster
camdecoster changed the base branch from v4.0 to main August 25, 2026 00:06
@camdecoster

Copy link
Copy Markdown
Contributor

@wf-r are you still interested in finishing this PR?

@wf-r

wf-r commented Nov 16, 2026

Copy link
Copy Markdown
Author

@wf-r are you still interested in finishing this PR?

Yes, very much so.

My last status was that it is ready for review (yet this was 3 months ago, so orobably an update to the current state of main would be in order).

@camdecoster

Copy link
Copy Markdown
Contributor

Ah, my comments never got added. I now see they all say pending. Sorry about that! I'll get my review fixed up and post an update.

# Conflicts:
#	src/traces/sankey/constants.js

@camdecoster camdecoster left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is a good start. Could you please make a few changes?

Comment on lines +238 to +254
valueformat: {
valType: 'string',
dflt: '',
description: [
'Sets the value formatting rule for the permanent link labels,',
'using d3 formatting mini-languages. Falls back to the trace-level',
'`valueformat` when empty.'
].join(' ')
},
valuesuffix: {
valType: 'string',
dflt: '',
description: [
'Adds a unit to follow the value in the permanent link labels.',
'Falls back to the trace-level `valuesuffix` when empty.'
].join(' ')
},

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's remove these in favor of relying on the trace attributes.

function linkModels(d) {
if(!d._linkModels) {
d._linkModels = d.graph.links
.filter(function(l) {return l.value;})

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's okay to use ES6 syntax. esbuild transpiles it.

Suggested change
.filter(function(l) {return l.value;})
.filter((l) => l.value)

Comment thread draftlogs/7888_add.md
@@ -0,0 +1,4 @@
- Add permanent on-diagram link labels to the Sankey trace via new `link.textinfo`, `link.texttemplate`, `link.texttemplatefallback`, `link.textfont`, `link.valueformat`, and `link.valuesuffix` attributes [[#7888](https://github.com/plotly/plotly.js/pull/7888)].

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- Add permanent on-diagram link labels to the Sankey trace via new `link.textinfo`, `link.texttemplate`, `link.texttemplatefallback`, `link.textfont`, `link.valueformat`, and `link.valuesuffix` attributes [[#7888](https://github.com/plotly/plotly.js/pull/7888)].
- Add Sankey trace link labels [[#7888](https://github.com/plotly/plotly.js/pull/7888)]

})
.attr('transform', linkLabelTransform);

sankeyLinkLabel.exit().remove();

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The labels don't fade in/out properly during transitions like the links do. Could you update this section to match the way links fade?

midX = (l.circularPathData.leftInnerExtent + l.circularPathData.rightInnerExtent) / 2;
midY = l.circularPathData.verticalFullExtent;
} else {
midX = (l.source.x1 + l.target.x0) / 2;

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It seems like the label should be centered at the middle of the arrow body and exclude the length of the arrow head. What do you think?

See these examples:

With arrow head Without arrow head
image image

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could you please remove all of these new mocks (and baselines) and update the sankey_circular_with_arrows family of mocks to test the new label functionality?


Lib.coerceFont(coerce, 'textfont', layout.font, { autoShadowDflt: true });

// permanent link text labels (opt-in via link.textinfo / link.texttemplate)

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
// permanent link text labels (opt-in via link.textinfo / link.texttemplate)

Comment on lines +602 to +603
source: l.source.label,
target: l.target.label,

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's update this to maintain the current pattern used in hovertemplate:

Suggested change
source: l.source.label,
target: l.target.label,
source: l.source,
target: l.target,

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants