Add attribute-based legends (colorlegend, sizelegend, symbollegend)
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 tolayout.colorlegend -
marker.sizelegend- Reference tolayout.sizelegend -
marker.symbollegend- Reference tolayout.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!
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.