plotly.js icon indicating copy to clipboard operation
plotly.js copied to clipboard

Add attribute-based legends (colorlegend, sizelegend, symbollegend)

Open Rhoahndur opened this issue 3 months ago • 1 comments

Implementation for Issue #5099 ( https://github.com/plotly/plotly.js/issues/5099 ) adds three new legend components that show unique values from marker attributes (color, size, symbol) rather than trace-based legends.

New components:

  • colorlegend: displays unique color values as swatches
  • sizelegend: displays size ranges as graduated circles
  • symbollegend: displays unique marker symbols

Features:

  • Click to toggle visibility of points with that attribute value (remains to be implemented)
  • Support for multiple legends (colorlegend, colorlegend2, etc.)
  • Configurable positioning, styling, and orientation
  • Works with scatter and scatter-variant traces

Summary

This PR implements attribute-based legends as requested in #5099.

Currently, Plotly.js legends are trace-centric (one entry per trace), which becomes unwieldy when multiple traces share visual attributes like color scales or size mappings across hundreds of points. This enhancement adds three new legend components that allow users to create separate legends based on marker attributes:

  • colorlegend - Discrete color swatch legend for categorical or binned color values
  • sizelegend - Graduated circle legend for size ranges
  • symbollegend - Symbol shape legend for marker symbols

New Trace Attributes

  • marker.colorlegend - Reference to layout.colorlegend
  • marker.sizelegend - Reference to layout.sizelegend
  • marker.symbollegend - Reference to layout.symbollegend

Example Usage

Plotly.newPlot('div', [{
  type: 'scatter',
  x: [1, 2, 3, 4],
  y: [10, 20, 15, 25],
  marker: {
    color: ['Species A', 'Species B', 'Species A', 'Species C'],
    colorlegend: 'colorlegend'
  }
}], {
  colorlegend: {
    title: { text: 'Species' },
    x: 1.02,
    y: 1
  }
});

## Test Plan


 npm run lint passes
 npm run schema regenerated
 Jasmine tests added for all three components
 Image mocks added: colorlegend_basic, sizelegend_basic, symbollegend_basic
 Manual testing in dev dashboard


Note: This is my first contribution to Plotly.js (one of two PRs I'm working on for this project). I've done my best to follow the existing patterns in the codebase (particularly the colorbar and legend components), but I'm very open to feedback on the implementation approach, code style, or anything else. Thank you for taking the time to review!

Rhoahndur avatar Nov 26 '25 21:11 Rhoahndur

The failing image tests (uniformtext_sunburst_treemap, treemap_textfit, treemap_sunburst_marker_colors, treemap_packages_colorscale_novalue, sunburst_coffee) are unrelated to my changes - I did not modify any sunburst or treemap code. These appear to be pre-existing issues or environment-specific failures.

Rhoahndur avatar Nov 27 '25 02:11 Rhoahndur