D3.js Complete Guide: Data-Driven Visualizations for the Web

1. What Is D3.js

D3.js (Data-Driven Documents) is a JavaScript library for creating data-driven interactive visualizations. Created by Mike Bostock in 2011, it is not a charting library — it is a low-level visualization toolkit that gives you complete control over every step from data to pixels. D3 renders visualizations using SVG, HTML, and CSS, running in all modern browsers.

Unlike high-level charting libraries such as Chart.js or Recharts, D3 does not provide pre-built chart components. Instead, it provides the fundamental tools to build any visualization: DOM manipulation, data binding, scales, shape generators, layout algorithms, and transitions. This flexibility makes D3 the choice of the New York Times, Observable, and thousands of data visualization projects.

2. Installation and Setup

Install via npm

npm install d3
# or
yarn add d3

# TypeScript types
npm install @types/d3 --save-dev

Import Options

// Import everything
import * as d3 from "d3";

// Import only what you need (smaller bundle)
import { select, selectAll } from "d3-selection";
import { scaleLinear, scaleBand } from "d3-scale";
import { axisBottom, axisLeft } from "d3-axis";
import { line, area, pie, arc } from "d3-shape";
import { transition } from "d3-transition";

CDN Script Tag

<script src="https://cdn.jsdelivr.net/npm/d3@7"></script>
<script>
  // d3 is available as a global
  d3.select("body").append("h1").text("Hello D3!");
</script>

3. Selections: select and selectAll

Selections are the core of D3. d3.select() picks the first matching DOM element, d3.selectAll() picks all matching elements. Selections support method chaining to modify attributes, styles, and content.

// Select a single element
const svg = d3.select("#chart");

// Select all matching elements
const circles = d3.selectAll("circle");

// Chain attribute and style modifications
d3.selectAll("rect")
  .attr("width", 50)
  .attr("height", 30)
  .attr("fill", "#3b82f6")
  .style("opacity", 0.8);

// Append new elements
d3.select("#chart")
  .append("svg")
  .attr("width", 600)
  .attr("height", 400)
  .append("circle")
  .attr("cx", 100)
  .attr("cy", 100)
  .attr("r", 40)
  .attr("fill", "tomato");

4. Data Binding: data / enter / exit / join

Data binding is the most powerful feature of D3. The data() method associates an array with DOM elements. When there are more data items than elements, enter() handles new items. When there are more elements than data, exit() handles removals. The update selection handles existing elements.

Classic enter/exit Pattern

const data = [10, 20, 35, 50, 25];

// Select all rects (initially none exist)
const bars = svg.selectAll("rect")
  .data(data);

// Enter: create new elements for new data
bars.enter()
  .append("rect")
  .attr("x", (d, i) => i * 60)
  .attr("y", (d) => 200 - d * 3)
  .attr("width", 50)
  .attr("height", (d) => d * 3)
  .attr("fill", "#3b82f6");

// Exit: remove elements without data
bars.exit().remove();

Modern join Method (D3 v5+)

const data = [10, 20, 35, 50, 25];

// join() handles enter, update, and exit in one call
svg.selectAll("rect")
  .data(data)
  .join("rect")
  .attr("x", (d, i) => i * 60)
  .attr("y", (d) => 200 - d * 3)
  .attr("width", 50)
  .attr("height", (d) => d * 3)
  .attr("fill", "#3b82f6");

// join() with enter/update/exit callbacks
svg.selectAll("rect")
  .data(data)
  .join(
    (enter) => enter.append("rect")
      .attr("fill", "green"),
    (update) => update
      .attr("fill", "blue"),
    (exit) => exit
      .attr("fill", "red")
      .transition().duration(500)
      .attr("opacity", 0)
      .remove()
  );

5. Scales

Scales map data values (domain) to visual values (range) such as pixel positions, colors, or sizes. They are the core tool for building charts.

Linear Scale (scaleLinear)

// Map data 0-100 to pixels 0-500
const xScale = d3.scaleLinear()
  .domain([0, 100])     // data range
  .range([0, 500]);     // pixel range

xScale(50);   // 250
xScale(100);  // 500
xScale.invert(250);  // 50 (reverse lookup)

Band Scale (scaleBand)

// Map categories to equal-width bands
const xScale = d3.scaleBand()
  .domain(["Mon", "Tue", "Wed", "Thu", "Fri"])
  .range([0, 500])
  .padding(0.2);  // gap between bands

xScale("Wed");           // 200 (pixel position)
xScale.bandwidth();      // 80 (width of each band)

Time Scale and Log Scale

// Time scale
const timeScale = d3.scaleTime()
  .domain([new Date("2025-01-01"), new Date("2025-12-31")])
  .range([0, 800]);

// Log scale (useful for data spanning orders of magnitude)
const logScale = d3.scaleLog()
  .domain([1, 10000])
  .range([0, 500]);

// Color scale
const colorScale = d3.scaleOrdinal(d3.schemeCategory10)
  .domain(["A", "B", "C", "D"]);

6. Axes

D3 axis generators automatically create SVG tick marks, labels, and reference lines from a scale. Use axisBottom, axisLeft, axisTop, and axisRight to set direction.

const margin = { top: 20, right: 20, bottom: 40, left: 50 };
const width = 600 - margin.left - margin.right;
const height = 400 - margin.top - margin.bottom;

const svg = d3.select("#chart")
  .append("svg")
  .attr("width", width + margin.left + margin.right)
  .attr("height", height + margin.top + margin.bottom)
  .append("g")
  .attr("transform",
    "translate(" + margin.left + "," + margin.top + ")");

const xScale = d3.scaleLinear()
  .domain([0, 100]).range([0, width]);
const yScale = d3.scaleLinear()
  .domain([0, 500]).range([height, 0]);

// Add bottom axis
svg.append("g")
  .attr("transform", "translate(0," + height + ")")
  .call(d3.axisBottom(xScale).ticks(10));

// Add left axis
svg.append("g")
  .call(d3.axisLeft(yScale)
    .ticks(5)
    .tickFormat(d => "\$" + d));

7. SVG Basics for D3

D3 primarily uses SVG for rendering. Understanding core SVG elements is essential for working with D3. The SVG coordinate system has its origin at the top-left, with y increasing downward.

<!-- Core SVG elements used in D3 -->
<svg width="400" height="300">
  <!-- Rectangle: x, y, width, height -->
  <rect x="10" y="10" width="80" height="50"
    fill="#3b82f6" rx="4" />

  <!-- Circle: cx, cy, r -->
  <circle cx="200" cy="100" r="30"
    fill="#ef4444" stroke="#000" stroke-width="2" />

  <!-- Line: x1, y1, x2, y2 -->
  <line x1="10" y1="200" x2="390" y2="200"
    stroke="#94a3b8" stroke-width="1" />

  <!-- Path: the most powerful SVG element -->
  <path d="M10 250 L100 200 L200 230 L300 180"
    fill="none" stroke="#10b981" stroke-width="2" />

  <!-- Text -->
  <text x="200" y="290" text-anchor="middle"
    font-size="14">Label</text>
  <!-- Group: transform applies to all children -->
  <g transform="translate(50, 50)">
    <rect width="20" height="20" fill="#8b5cf6" />
  </g>
</svg>

8. Bar Chart

Bar charts are the most common D3 chart type. Below is a complete vertical bar chart example with scales, axes, and data labels.

const data = [
  { label: "React", value: 42 },
  { label: "Vue", value: 30 },
  { label: "Angular", value: 22 },
  { label: "Svelte", value: 18 },
  { label: "Solid", value: 12 },
];

const margin = { top: 20, right: 20, bottom: 40, left: 50 };
const width = 500 - margin.left - margin.right;
const height = 300 - margin.top - margin.bottom;

const svg = d3.select("#bar-chart")
  .append("svg")
  .attr("width", width + margin.left + margin.right)
  .attr("height", height + margin.top + margin.bottom)
  .append("g")
  .attr("transform",
    "translate(" + margin.left + "," + margin.top + ")");

const x = d3.scaleBand()
  .domain(data.map((d) => d.label))
  .range([0, width])
  .padding(0.2);

const y = d3.scaleLinear()
  .domain([0, d3.max(data, (d) => d.value)])
  .range([height, 0]);

// Axes
svg.append("g")
  .attr("transform", "translate(0," + height + ")")
  .call(d3.axisBottom(x));
svg.append("g").call(d3.axisLeft(y));

// Bars
svg.selectAll("rect")
  .data(data)
  .join("rect")
  .attr("x", (d) => x(d.label))
  .attr("y", (d) => y(d.value))
  .attr("width", x.bandwidth())
  .attr("height", (d) => height - y(d.value))
  .attr("fill", "#3b82f6")
  .attr("rx", 4);

9. Line Chart

Line charts use the d3.line() generator to convert data points into SVG paths. They are ideal for showing trends over time.

const data = [
  { date: new Date("2025-01"), value: 120 },
  { date: new Date("2025-02"), value: 180 },
  { date: new Date("2025-03"), value: 150 },
  { date: new Date("2025-04"), value: 220 },
  { date: new Date("2025-05"), value: 280 },
  { date: new Date("2025-06"), value: 250 },
];

const x = d3.scaleTime()
  .domain(d3.extent(data, (d) => d.date))
  .range([0, width]);

const y = d3.scaleLinear()
  .domain([0, d3.max(data, (d) => d.value)])
  .range([height, 0]);

// Line generator
const lineGen = d3.line()
  .x((d) => x(d.date))
  .y((d) => y(d.value))
  .curve(d3.curveMonotoneX);  // smooth curve

// Draw the line
svg.append("path")
  .datum(data)
  .attr("fill", "none")
  .attr("stroke", "#3b82f6")
  .attr("stroke-width", 2.5)
  .attr("d", lineGen);

// Add data points
svg.selectAll("circle")
  .data(data)
  .join("circle")
  .attr("cx", (d) => x(d.date))
  .attr("cy", (d) => y(d.value))
  .attr("r", 4)
  .attr("fill", "#3b82f6");

10. Pie and Donut Charts

Pie charts use d3.pie() to compute angles and d3.arc() to generate arc paths. Set innerRadius > 0 to create a donut chart.

const data = [
  { label: "Desktop", value: 55 },
  { label: "Mobile", value: 35 },
  { label: "Tablet", value: 10 },
];

const radius = 150;
const color = d3.scaleOrdinal(d3.schemeCategory10);

// Pie layout computes start/end angles
const pieLayout = d3.pie()
  .value((d) => d.value)
  .sort(null);

// Arc generator
const arcGen = d3.arc()
  .innerRadius(60)    // 0 for pie, >0 for donut
  .outerRadius(radius);

const g = svg.append("g")
  .attr("transform",
    "translate(" + (width / 2) + "," + (height / 2) + ")");

// Draw arcs
g.selectAll("path")
  .data(pieLayout(data))
  .join("path")
  .attr("d", arcGen)
  .attr("fill", (d, i) => color(i))
  .attr("stroke", "#fff")
  .attr("stroke-width", 2);

// Add labels
g.selectAll("text")
  .data(pieLayout(data))
  .join("text")
  .attr("transform", (d) =>
    "translate(" + arcGen.centroid(d) + ")")
  .attr("text-anchor", "middle")
  .attr("font-size", "12px")
  .text((d) => d.data.label);

11. Transitions and Animations

The D3 transition() method creates smooth animations between attribute changes. It supports custom duration, delay, easing functions, and chained transitions.

// Basic transition
svg.selectAll("rect")
  .data(data)
  .join("rect")
  .attr("x", (d) => x(d.label))
  .attr("y", height)              // start from bottom
  .attr("width", x.bandwidth())
  .attr("height", 0)              // start with zero height
  .attr("fill", "#3b82f6")
  .transition()                   // begin transition
  .duration(800)                  // 800ms
  .delay((d, i) => i * 100)       // stagger bars
  .ease(d3.easeCubicOut)          // easing function
  .attr("y", (d) => y(d.value))   // animate to final y
  .attr("height", (d) => height - y(d.value));

// Chained transitions
d3.select("circle")
  .transition()
  .duration(500)
  .attr("r", 50)
  .attr("fill", "red")
  .transition()                   // chain another
  .duration(500)
  .attr("r", 20)
  .attr("fill", "blue");

12. Event Handling

D3 uses the .on() method to listen to DOM events. Callback functions receive the event object and bound data, enabling hover highlights, tooltips, and click interactions.

// Hover highlight
svg.selectAll("rect")
  .on("mouseenter", function (event, d) {
    d3.select(this)
      .attr("fill", "#2563eb")
      .attr("opacity", 0.8);
  })
  .on("mouseleave", function (event, d) {
    d3.select(this)
      .attr("fill", "#3b82f6")
      .attr("opacity", 1);
  });

// Tooltip
const tooltip = d3.select("body")
  .append("div")
  .style("position", "absolute")
  .style("background", "#1e293b")
  .style("color", "#f1f5f9")
  .style("padding", "8px 12px")
  .style("border-radius", "6px")
  .style("font-size", "13px")
  .style("pointer-events", "none")
  .style("opacity", 0);

svg.selectAll("circle")
  .on("mouseover", function (event, d) {
    tooltip
      .style("opacity", 1)
      .html("Value: " + d.value)
      .style("left", (event.pageX + 10) + "px")
      .style("top", (event.pageY - 10) + "px");
  })
  .on("mouseout", function () {
    tooltip.style("opacity", 0);
  });

13. Responsive Charts

Use the SVG viewBox attribute to make charts scale automatically, and combine with ResizeObserver for truly responsive designs.

// Method 1: viewBox (simplest)
const svg = d3.select("#chart")
  .append("svg")
  .attr("viewBox", "0 0 600 400")
  .style("width", "100%")
  .style("height", "auto");
// Chart scales to container automatically

// Method 2: ResizeObserver (dynamic redraw)
function createChart(container) {
  const observer = new ResizeObserver((entries) => {
    const { width } = entries[0].contentRect;
    const height = width * 0.6;  // aspect ratio

    // Clear and redraw
    d3.select(container).selectAll("*").remove();
    const svg = d3.select(container)
      .append("svg")
      .attr("width", width)
      .attr("height", height);

    // Recalculate scales with new dimensions
    const x = d3.scaleLinear()
      .domain([0, 100])
      .range([40, width - 20]);
    // ... draw chart with new dimensions
  });
  observer.observe(container);
}

14. D3 with React

The recommended way to use D3 in React is to get a container reference with useRef and run D3 code inside useEffect. React manages the component lifecycle while D3 handles SVG rendering.

import React, { useRef, useEffect } from "react";
import * as d3 from "d3";

function BarChart({ data }) {
  const svgRef = useRef(null);

  useEffect(() => {
    if (!data || !svgRef.current) return;

    const svg = d3.select(svgRef.current);
    svg.selectAll("*").remove();  // clear previous

    const width = 500, height = 300;
    const margin = { top: 20, right: 20,
      bottom: 30, left: 40 };
    const innerW = width - margin.left - margin.right;
    const innerH = height - margin.top - margin.bottom;

    const g = svg
      .attr("width", width)
      .attr("height", height)
      .append("g")
      .attr("transform",
        "translate(" + margin.left + ","
        + margin.top + ")");

    const x = d3.scaleBand()
      .domain(data.map((d) => d.name))
      .range([0, innerW]).padding(0.2);

    const y = d3.scaleLinear()
      .domain([0, d3.max(data, (d) => d.val)])
      .range([innerH, 0]);

    g.append("g")
      .attr("transform", "translate(0," + innerH + ")")
      .call(d3.axisBottom(x));
    g.append("g").call(d3.axisLeft(y));

    g.selectAll("rect")
      .data(data)
      .join("rect")
      .attr("x", (d) => x(d.name))
      .attr("y", (d) => y(d.val))
      .attr("width", x.bandwidth())
      .attr("height", (d) => innerH - y(d.val))
      .attr("fill", "#3b82f6");
  }, [data]);

  return <svg ref={svgRef} />;
}

Approach 2: React Renders SVG, D3 for Math

function BarChartReact({ data }) {
  const width = 500, height = 300;
  const margin = { top: 20, right: 20,
    bottom: 30, left: 40 };

  const x = d3.scaleBand()
    .domain(data.map((d) => d.name))
    .range([margin.left, width - margin.right])
    .padding(0.2);

  const y = d3.scaleLinear()
    .domain([0, d3.max(data, (d) => d.val)])
    .range([height - margin.bottom, margin.top]);

  return (
    <svg width={width} height={height}>
      {data.map((d, i) => (
        <rect
          key={i}
          x={x(d.name)}
          y={y(d.val)}
          width={x.bandwidth()}
          height={y(0) - y(d.val)}
          fill="#3b82f6"
        />
      ))}
    </svg>
  );
}

15. GeoJSON and Maps

D3 includes powerful geographic projections and path generators that render GeoJSON/TopoJSON data as interactive maps. It supports dozens of projection types.

// Load and render a world map
const projection = d3.geoNaturalEarth1()
  .scale(150)
  .translate([width / 2, height / 2]);

const pathGen = d3.geoPath().projection(projection);

// Load GeoJSON data
d3.json("https://unpkg.com/world-atlas@2"
  + "/countries-110m.json")
  .then((world) => {
    const countries = topojson.feature(
      world, world.objects.countries
    );

    svg.selectAll("path")
      .data(countries.features)
      .join("path")
      .attr("d", pathGen)
      .attr("fill", "#cbd5e1")
      .attr("stroke", "#64748b")
      .attr("stroke-width", 0.5);
  });

// Choropleth: color by data value
const colorScale = d3.scaleSequential()
  .domain([0, 100])
  .interpolator(d3.interpolateBlues);

svg.selectAll("path")
  .attr("fill", (d) =>
    colorScale(dataMap.get(d.id) || 0));

16. Force-Directed Graphs

Force-directed graphs use physics simulation to lay out network nodes. The d3-force module provides several forces: link force, charge force, center force, and collision force.

const nodes = [
  { id: "A" }, { id: "B" }, { id: "C" },
  { id: "D" }, { id: "E" },
];
const links = [
  { source: "A", target: "B" },
  { source: "A", target: "C" },
  { source: "B", target: "D" },
  { source: "C", target: "E" },
];

const simulation = d3.forceSimulation(nodes)
  .force("link", d3.forceLink(links)
    .id((d) => d.id).distance(100))
  .force("charge", d3.forceManyBody()
    .strength(-200))
  .force("center", d3.forceCenter(
    width / 2, height / 2))
  .force("collision", d3.forceCollide(20));

// Draw links
const link = svg.selectAll("line")
  .data(links)
  .join("line")
  .attr("stroke", "#94a3b8")
  .attr("stroke-width", 2);

// Draw nodes
const node = svg.selectAll("circle")
  .data(nodes)
  .join("circle")
  .attr("r", 15)
  .attr("fill", "#3b82f6")
  .call(d3.drag()
    .on("start", dragStart)
    .on("drag", dragging)
    .on("end", dragEnd));

// Update positions on each tick
simulation.on("tick", () => {
  link
    .attr("x1", (d) => d.source.x)
    .attr("y1", (d) => d.source.y)
    .attr("x2", (d) => d.target.x)
    .attr("y2", (d) => d.target.y);
  node
    .attr("cx", (d) => d.x)
    .attr("cy", (d) => d.y);
});

function dragStart(event, d) {
  if (!event.active)
    simulation.alphaTarget(0.3).restart();
  d.fx = d.x; d.fy = d.y;
}
function dragging(event, d) {
  d.fx = event.x; d.fy = event.y;
}
function dragEnd(event, d) {
  if (!event.active)
    simulation.alphaTarget(0);
  d.fx = null; d.fy = null;
}

17. D3.js Best Practices

• Use the margin convention: Define a margin object (top/right/bottom/left) and subtract margins from SVG dimensions to calculate the inner drawing area. Every chart should follow this pattern.
• Prefer join() over enter/exit: The D3 v5+ join() method is cleaner, automatically handles enter, update, and exit selections, and reduces boilerplate.
• Import modules selectively: Do not import the entire d3 library. Import only the modules you need (d3-scale, d3-selection, etc.) to significantly reduce bundle size.
• Use viewBox for responsiveness: Set the SVG viewBox attribute instead of fixed width/height to let charts adapt automatically to container size.
• Use data keys for stable binding: Pass a key function to data() (e.g., d => d.id) to ensure elements match correctly during data updates instead of relying on index.
• Clean up timers and event listeners: In the React useEffect cleanup function, stop simulations, cancel transitions, and remove event listeners to prevent memory leaks.
• Use transitions judiciously: Animations should enhance understanding, not distract. Keep durations between 200-800ms and avoid triggering complex animations on many elements simultaneously.
• Add ARIA attributes for accessibility: Add role="img" and aria-label to SVG, add title elements to data points, ensuring screen readers can understand chart content.

18. Common D3 Modules Reference

Frequently Asked Questions

What is D3.js and what is it used for?

D3.js (Data-Driven Documents) is a JavaScript visualization library for creating dynamic, interactive data visualizations in the browser using SVG, HTML, and CSS. It binds data to DOM elements and applies data-driven transformations to create charts, maps, graphs, and dashboards.

How do I install D3.js?

Install via npm with "npm install d3" and import with "import * as d3 from 'd3'". You can also import individual modules like d3-scale or d3-selection. Alternatively, load from a CDN with a script tag.

What is the difference between select and selectAll?

d3.select() selects the first matching DOM element while d3.selectAll() selects all matching elements. Both accept CSS selectors and return selections that support method chaining for modifying attributes, styles, and binding data.

How does enter/update/exit work in D3?

enter() handles new data items that need new elements created. The update selection handles existing elements with new data. exit() handles elements that no longer have corresponding data and should be removed. The D3 v7 join() method combines all three in one call.

What are D3 scales and why are they important?

Scales map data values (domain) to visual values (range). scaleLinear maps continuous numbers, scaleBand maps categories, scaleTime maps dates, and scaleLog uses logarithmic mapping. They are the core tool for converting raw data into coordinates that fit your chart dimensions.

How do I use D3 with React?

Use useRef to get a reference to an SVG or div container, then run D3 code in useEffect to manipulate it. React manages the component lifecycle while D3 handles SVG rendering. For simple charts, you can also use only D3 scales and let React render SVG elements directly.

How do I create responsive D3 charts?

Use SVG viewBox instead of fixed width/height. Set viewBox="0 0 width height" and CSS width to 100%. Or use ResizeObserver to detect size changes and redraw.

Can D3 create maps and geographic visualizations?

Yes. Use d3-geo projections (geoMercator, geoNaturalEarth1, etc.) to convert longitude/latitude to screen coordinates. Load GeoJSON/TopoJSON data and use geoPath to render as SVG paths. Supports choropleth maps, point maps, and custom projections.