Skip to main content

D3.js

What is D3.js​

D3 (Data-Driven Documents) is the foundational JavaScript library for web data visualization. It uses web standards (SVG, Canvas, HTML) and provides a comprehensive toolkit for scales, shapes, axes, geographic projections, force simulations, hierarchical layouts, and more. ISC licensed, ~110k GitHub stars, ~4–5M weekly npm downloads for the umbrella package. Currently at v7.x.

D3 is modular — ~30 standalone submodules (d3-scale, d3-shape, d3-array, d3-geo, d3-force, d3-hierarchy, etc.) that can be imported individually.

Both Recharts and VisX use D3 submodules internally — D3 is the mathematical foundation of our visualization stack.

caution

Advanced, situational option. D3's imperative API conflicts with React's rendering model. For React projects, prefer Recharts, Apache ECharts, or VisX. Use raw D3 only when no higher-level abstraction meets your needs.

When D3 shines​

  • Completely novel visualization forms — when no library has a pre-built component for what you need, D3 gives you the lowest-level building blocks.
  • Force-directed graph layouts — d3-force is the gold standard for physics-based network layouts (social networks, dependency graphs).
  • Canvas rendering for massive datasets — D3 + Canvas can render hundreds of thousands of points where SVG-based libraries degrade.
  • Non-React projects — vanilla JS, Web Components, or server-side SVG generation where VisX and Recharts don't apply.
  • Geographic visualizations — d3-geo supports 20+ map projections with fine-grained control.
  • Observable notebooks — D3 is the native language of Observable, the go-to platform for data journalism and exploratory visualization.
  • Precise animation control — d3-transition provides interpolated animations with granular easing and timing.

Why it's not our default​

  • Imperative API conflicts with React — D3's d3-selection manipulates the DOM directly, clashing with React's virtual DOM reconciliation. Using both requires careful useRef + useEffect patterns to isolate D3 from React's render cycle.
  • Steep learning curve — selections, data joins, enter/update/exit, scales, and generators take significant time to master. D3 has one of the steepest learning curves in frontend development.
  • No out-of-the-box charts — D3 is a visualization toolkit, not a chart library. A basic bar chart easily requires 100+ lines of code.
  • No official React bindings — community approaches exist but none is standard.
  • Bundle size — the full d3 umbrella is ~300KB+ minified. Tree-shaking requires importing individual submodules instead of the umbrella package.

How D3 relates to our other tools​

Our visualization stack forms an abstraction spectrum:

LevelToolApproach
Highestshadcn/ui chartsPre-styled Recharts wrappers
HighRechartsDeclarative JSX components
MediumApache EChartsConfiguration-driven (JSON options)
LowVisXComposable React + D3 primitives
LowestD3.jsFull imperative control
  • Recharts uses D3 submodules internally but hides them completely behind declarative JSX props.
  • VisX exposes D3 concepts (scales, shapes) but wraps them in React components.
  • Raw D3 gives you everything — math, rendering, transitions — but you own all the complexity.

Using D3 in React​

If you must use D3 in a React project:

  • Use useRef to get a DOM reference and useEffect to run D3 code — let D3 own its subtree.
  • Don't let React re-render elements that D3 manages.
  • The safest pattern is using D3 only for computation (d3-scale, d3-array, d3-force) while letting React handle SVG/Canvas rendering.
  • For most needs, prefer VisX — it provides React wrappers for D3's math without the DOM conflict.
tip

The safest pattern in React is to use D3 only for computation (scales, layouts, data transforms) and let React render the SVG/Canvas. This is essentially what VisX does — consider using it instead of hand-rolling the integration.

When to use​

  • Force-directed graph layouts or physics simulations
  • Canvas-rendered visualizations with very large datasets
  • Non-React projects where VisX and Recharts don't apply
  • You need a D3 module's computation (e.g., d3-force, d3-geo) that has no VisX equivalent
  • Prototyping novel visualization concepts in Observable notebooks

When NOT to use​

  • React dashboard projects — use Recharts or Apache ECharts
  • React projects needing custom but composable charts — use VisX
  • Teams without D3 experience on tight deadlines
  • Simple charts where a higher-level library handles the job in a few lines of code

Resources​