ggaction 0.0.5

Legends

Grouped density area chart of car acceleration
Derived density paths with grouped color and guides.

At a glance

Action Shortest call Inference/defaults Result
createLegend createLegend() Current/unique compatible mark; right position Categorical, size, stroke-width, gradient, interval, or opacity guide
editLegend editLegend({ position: "left" }) Unique existing legend; omitted properties retained Rematerialized layout and appearance
Focused edits editLegendLabels({ fontSize: 11 }) Same target inference as editLegend One legend component rematerialized
removeLegend removeLegend({ target: "points" }) Existing legend owner All owned legend blocks removed

Legends are inferred from final mark encodings and materialized as concrete graphics. Start with the family that matches the encoded channel and use the editing page when changing an existing guide.

Supported legend families

| Legend family | Supported marks | Channels | | — | — | — | | Categorical | point, line, area, bar, rect, arc | color, shape, strokeDash, or compatible composites | | Continuous gradient | point, aggregate bar, rect | sequential color | | Discretized interval | point | quantize, quantile, or threshold color | | Sampled | point, line, rule | field opacity, size, or strokeWidth |

Focused legend families

Categorical legendsCreate categorical, size, and interval guides and control their layout. Continuous legendsGradient color and sampled opacity guides. Composite symbolsLayered line, point, and swatch recipes plus optional borders. Edit and removeAtomic component edits, rematerialization, trace, and removal.

Errors and limitations

Continuous color legends support point, aggregate-bar, and rect marks. Field opacity and discretized continuous legends remain point-only. Interactive legends are unsupported. Combined point-series and quantitative-size legends require a right or left side position so both blocks remain in one vertical stack. A left block must fit outside any left y-axis guides; use sufficient margin and offset. Standalone stroke-width legends currently use the right side and accept count when created. Edit their quantitative mapping through editScale; editLegend support for that sampled block is not yet part of the public contract. Right-side layout requires sufficient right margin; bottom layout requires sufficient bottom margin; top layout requires enough top margin for its title, item grid, offset, and optional border. The library reports a layout error instead of resizing the Canvas or dropping symbol layers.

Guides · Series encodings · Canvas · Troubleshooting