How do I add a color legend to my D3 chart using d3-legend?

Include d3-legend after D3, create a D3 scale, append a 'g' element to your SVG, and call d3.legendColor() with the scale. The README provides a code example for quantize scales with label formatting.

Is d3-legend compatible with D3 version 5 or 6?

d3-legend v4 is designed for D3 v4 and later; for newer versions, check the documentation for adjustments, as the npm package no longer binds globally. Use the v3 branch for D3 v3 compatibility.

d3-legend vs building legends manually in D3 – which should I choose?

d3-legend saves time with pre-built layouts and styling, but manual creation offers more control. For standard legends, d3-legend is efficient; for highly custom or interactive needs, manual might be better.

Can I use d3-legend with React or Vue components?

Yes, but it requires integrating D3 and SVG within the framework, such as using React refs to manage D3 selections. It's not a native component, so expect extra setup compared to framework-specific libraries.

How to style the legend with custom CSS classes?

Use the .useClass(true) method in the legend configuration, then target generated classes like 'legend-color' in your CSS. The README mentions this for flexible styling without JavaScript overrides.

Is d3-legend still being updated or maintained?

No, the README states it's in maintenance mode with no new features planned. It's stable for current use but won't receive updates or bug fixes beyond critical issues.

Open-Awesome

d3-legend

Apache-2.0JavaScriptv2.25.5

A reusable D3.js legend component for color, size, and symbol scales in SVG visualizations.

Visit Website GitHub

724 stars103 forks0 contributors

What is d3-legend?

d3-legend is a reusable legend component for D3.js that generates legends for color, size, and symbol scales in SVG-based data visualizations. It solves the problem of manually creating and styling legends, providing a consistent, configurable way to explain visual encodings in charts and maps.

Target Audience

Data visualization developers using D3.js who need to add professional, customizable legends to their SVG charts, dashboards, or interactive maps.

Value Proposition

Developers choose d3-legend because it integrates seamlessly with D3 scales, reduces boilerplate code for legend creation, and offers flexible styling through CSS classes, all while following D3's familiar API patterns.

Overview

A reusable d3 legend component.

Use Cases

Best For

Adding color legends to choropleth maps or heatmaps
Creating size legends for bubble charts or scatter plots
Displaying symbol legends for categorical data in visualizations
Building interactive dashboards with D3.js that require clear scale explanations
Styling legends consistently across multiple charts in a project
Quickly prototyping data visualizations with professional-looking legends

Not Ideal For

Projects built with React, Vue, or other modern frameworks that prefer integrated, declarative charting components
Applications requiring advanced legend interactions like click-to-filter or real-time animations without manual D3 updates
Teams needing ongoing feature development or active community support, as the library is in maintenance mode with no new features

Pros & Cons

Pros

Seamless D3 Integration

Directly works with D3 scales and follows D3's data-binding patterns, making it a natural extension for existing D3 visualizations without extra abstractions.

CSS Styling Flexibility

Supports CSS classes via methods like .useClass(true), allowing easy customization to match project designs without modifying core JavaScript code.

Reduces Boilerplate Code

Eliminates the need to manually draw and position SVG legend elements, saving development time for common legend types like color or size scales.

Stable and Mature

The library is in maintenance mode, ensuring a stable API with minimal breaking changes, which is reliable for production environments.

Cons

Maintenance Mode Limitations

No new features or updates are planned, as stated in the README, which could lead to compatibility issues with future D3 versions or missing modern visualization needs.

D3 Ecosystem Lock-in

Heavily dependent on D3.js and SVG; if a project migrates away from D3, the legend component becomes obsolete or requires significant reimplementation.

Limited Legend Types

Only covers color, size, and symbol scales, lacking built-in support for other encodings like opacity or complex interactive legends without custom code.

Frequently Asked Questions

Related Projects

Textures.js

Textures.js is a JavaScript library for creating SVG patterns

Stars6,079

Forks220

Last commit3 years ago

crossfilter

Fast n-dimensional filtering and grouping of records.

Stars1,757

Forks190

Last commit2 years ago

d3-annotation

Use d3-annotation with built-in annotation types, or extend it to make custom annotations. It is made for d3-v4 in SVG.

Stars762

Forks73