D3.js Data Visualization Patterns

Quick Guide: D3 v7 is fully modular ES modules. Use
selection.join()
for the data join (replaces manual enter/update/exit). Prefer modular imports (
d3-selection
,
d3-scale
, etc.) to reduce bundle size. Scales map data domains to visual ranges; axes render tick marks from scales. Shape generators (
d3.line
,
d3.arc
,
d3.area
) produce SVG path strings from data arrays. Transitions animate attribute/style changes with automatic interpolation. For framework integration, let D3 handle data computation (scales, layouts, shapes) and let your framework own the DOM.

<critical_requirements>

CRITICAL: Before Using This Skill

All code must follow project conventions in CLAUDE.md (kebab-case, named exports, import ordering,
import type
, named constants)

(You MUST use
selection.join()
for data joins — NOT manual enter/append/merge/exit chains)

(You MUST use modular imports (
d3-selection
,
d3-scale
,
d3-shape
) — NOT
import * as d3 from "d3"
in production bundles)

(You MUST use named constants for ALL visual dimensions, colors, and timing values — NO magic numbers)

(You MUST type D3 selections and scales with TypeScript generics —
Selection<SVGGElement, Datum, ...>
,
ScaleLinear<number, number>
)

</critical_requirements>

Auto-detection: D3, d3, d3.js, d3-selection, d3-scale, d3-shape, d3-axis, d3-transition, d3-force, d3-geo, d3-zoom, d3-brush, d3-drag, d3-array, selection.join, data join, enter update exit, scaleLinear, scaleBand, scaleTime, axisBottom, axisLeft, forceSimulation, geoPath, geoMercator, line generator, arc generator, SVG visualization, data-driven documents

When to use:

Building custom SVG/Canvas data visualizations from scratch
Bindings between data arrays and DOM elements (the data join)
Mapping data domains to pixel ranges (scales and axes)
Generating SVG paths from data (lines, arcs, areas, pies)
Animating data transitions with interpolated attributes
Force-directed graph layouts and geographic map projections
Adding zoom, brush, and drag interactions to visualizations

When NOT to use:

Standard chart types (bar, line, pie) with minimal customization — use a charting library built on D3
Dashboards with many chart widgets — use a higher-level charting library
Simple data tables or non-graphical data display

Key patterns covered:

Selections and the data join (
```
selection.data().join()
```
)
Scales (linear, band, time, ordinal) and axes
Shape generators (line, area, arc, pie, stack)
Transitions and animated updates
Force-directed graph layouts
Geographic projections and choropleth maps
Zoom, brush, and drag interactions
Framework integration: D3 for math, framework for DOM
Responsive SVG with viewBox
TypeScript typing for D3

Detailed Resources:

examples/core.md - Selections, data joins, scales, axes, shapes, responsive SVG
examples/interaction.md - Transitions, zoom, brush, drag, tooltips
examples/advanced.md - Force layouts, geo projections, framework integration patterns
reference.md - Module reference, decision frameworks, anti-patterns

Philosophy

D3 is a low-level visualization grammar, not a charting library. It provides primitives for binding data to DOM elements and applying data-driven transformations. This gives maximum control at the cost of more code than higher-level alternatives.

Core mental model:

Select elements (existing or placeholder)
Bind data to selections with
```
.data()
```
Join to create/update/remove elements with
```
.join()
```
Encode data as visual attributes with scales
Annotate with axes, labels, legends
Animate changes with transitions

D3 v7 key decisions:

Pure ES modules — use modular imports for tree-shaking
```
selection.join()
```
replaces manual enter/update/exit boilerplate
TypeScript types ship with each module (no
```
@types/d3
```
needed for core packages, but available for convenience)
Works with any framework — D3 handles computation, your framework handles DOM rendering

When NOT to use D3 directly:

Standard charts with minimal customization (use a charting library)
Rapid prototyping where development speed matters more than customization
Teams without SVG/visualization experience

</philosophy>

Core Patterns

Pattern 1: Selections and the Data Join

The data join is D3's core pattern: bind an array of data to DOM elements, then use

.join()

to create, update, and remove elements as data changes.

typescript

import { select } from "d3-selection";

const BAR_HEIGHT = 30;
const BAR_GAP = 5;

// Select, bind data, join
select(svgElement)
  .selectAll<SVGRectElement, number>("rect")
  .data(values, (d) => String(d)) // key function for identity
  .join("rect") // enter + update merged
  .attr("y", (_, i) => i * (BAR_HEIGHT + BAR_GAP))
  .attr("width", (d) => xScale(d))
  .attr("height", BAR_HEIGHT);

Why good:

join("rect")

handles enter/update/exit in one call, key function ensures correct element-data binding across updates, typed selection generics

For advanced join with separate enter/update/exit callbacks, see examples/core.md Pattern 1.

Pattern 2: Scales — Mapping Data to Pixels

Scales are functions that map an input domain (data values) to an output range (pixel positions, colors).

typescript

import { scaleLinear, scaleBand, scaleTime, scaleOrdinal } from "d3-scale";

const CHART_WIDTH = 600;
const CHART_HEIGHT = 400;

// Continuous: numbers -> pixels
const x = scaleLinear<number>()
  .domain([0, max(data, (d) => d.value)!])
  .range([0, CHART_WIDTH]);

// Categorical: strings -> pixel bands (bar charts)
const y = scaleBand<string>()
  .domain(data.map((d) => d.label))
  .range([0, CHART_HEIGHT])
  .padding(0.1);

// Time: Date -> pixels
const timeScale = scaleTime<number>()
  .domain([startDate, endDate])
  .range([0, CHART_WIDTH]);

Why good: TypeScript generics on scales, domain derived from data with

max()

.padding()

on band scale for gaps between bars

See examples/core.md Pattern 2 for ordinal color scales and

scaleLog

scaleSqrt

patterns.

Pattern 3: Axes — Rendering Scale Tick Marks

Axes are SVG groups generated from a scale. Render with

selection.call(axis)

typescript

import { axisBottom, axisLeft } from "d3-axis";
import { format } from "d3-format";

const TICK_COUNT = 5;

// Create axes from scales
const xAxis = axisBottom(xScale).ticks(TICK_COUNT).tickFormat(format(",.0f"));
const yAxis = axisLeft(yScale);

// Render into <g> containers
svg
  .append("g")
  .attr("transform", `translate(0,${CHART_HEIGHT - MARGIN_BOTTOM})`)
  .call(xAxis);

svg.append("g").attr("transform", `translate(${MARGIN_LEFT},0)`).call(yAxis);

Why good: axes derived from scales (always in sync),

selection.call()

pattern for reusable rendering,

d3-format

for tick label formatting

See examples/core.md Pattern 3 for time axes and grid line patterns.

Pattern 4: Shape Generators — SVG Paths from Data

Shape generators are functions that take data arrays and produce SVG

attribute strings.

typescript

import { line, area, arc, pie, curveMonotoneX } from "d3-shape";
import type { PieArcDatum } from "d3-shape";

// Line generator
const lineGen = line<DataPoint>()
  .x((d) => xScale(d.date))
  .y((d) => yScale(d.value))
  .curve(curveMonotoneX);

svg
  .append("path")
  .datum(data)
  .attr("d", lineGen)
  .attr("fill", "none")
  .attr("stroke", "steelblue");

// Pie + arc generators
const INNER_RADIUS = 0;
const OUTER_RADIUS = 150;

const pieGen = pie<SliceData>().value((d) => d.value);
const arcGen = arc<PieArcDatum<SliceData>>()
  .innerRadius(INNER_RADIUS)
  .outerRadius(OUTER_RADIUS);

svg
  .selectAll("path")
  .data(pieGen(sliceData))
  .join("path")
  .attr("d", arcGen)
  .attr("fill", (d) => colorScale(d.data.label));

Why good: generators configured once then reused,

.curve()

for smooth interpolation, typed

PieArcDatum

generic for pie data, named radius constants

See examples/core.md Pattern 4 for area charts and stacked layouts.

Pattern 5: Responsive SVG with viewBox

Use the

viewBox

attribute so SVG scales to its container without JS resize handlers.

typescript

const VIEWBOX_WIDTH = 960;
const VIEWBOX_HEIGHT = 500;

const svg = select(container)
  .append("svg")
  .attr("viewBox", `0 0 ${VIEWBOX_WIDTH} ${VIEWBOX_HEIGHT}`)
  .attr("preserveAspectRatio", "xMidYMid meet")
  .style("width", "100%")
  .style("height", "auto");

Why good: SVG scales automatically, no resize listeners needed, chart dimensions stay consistent regardless of container size

For dynamic resizing with

ResizeObserver

, see examples/core.md Pattern 5.

Pattern 6: Transitions — Animated Data Updates

Transitions interpolate attributes and styles over time with easing.

typescript

import { transition } from "d3-transition";
import { easeCubicOut } from "d3-ease";

const TRANSITION_DURATION_MS = 750;
const STAGGER_DELAY_MS = 50;

select(svgElement)
  .selectAll<SVGRectElement, DataPoint>("rect")
  .data(newData, (d) => d.id)
  .join(
    (enter) =>
      enter
        .append("rect")
        .attr("width", 0)
        .call((s) =>
          s
            .transition()
            .duration(TRANSITION_DURATION_MS)
            .attr("width", (d) => xScale(d.value)),
        ),
    (update) =>
      update.call((s) =>
        s
          .transition()
          .duration(TRANSITION_DURATION_MS)
          .attr("width", (d) => xScale(d.value)),
      ),
    (exit) =>
      exit.call((s) =>
        s
          .transition()
          .duration(TRANSITION_DURATION_MS)
          .attr("width", 0)
          .remove(),
      ),
  );

Why good: enter/update/exit each have distinct animated behavior, stagger creates cascading effect, named timing constants

See examples/interaction.md Pattern 1 for easing functions and chained transitions.

Pattern 7: Zoom and Pan

Apply zoom behavior with

d3.zoom()

and transform the visualization on zoom events.

typescript

import { zoom, zoomIdentity } from "d3-zoom";
import type { D3ZoomEvent } from "d3-zoom";

const MIN_ZOOM = 0.5;
const MAX_ZOOM = 32;

const zoomBehavior = zoom<SVGSVGElement, unknown>()
  .scaleExtent([MIN_ZOOM, MAX_ZOOM])
  .on("zoom", (event: D3ZoomEvent<SVGSVGElement, unknown>) => {
    chartGroup.attr("transform", event.transform.toString());
  });

svg.call(zoomBehavior);

Why good: typed zoom event and element generics, scale extent prevents over-zoom, transform applied to inner group (not the SVG itself)

See examples/interaction.md Pattern 2 for semantic zoom and programmatic zoom controls.

Pattern 8: Force-Directed Graph Layout

Force simulations position nodes using physics-based forces (repulsion, attraction, centering).

typescript

import {
  forceSimulation,
  forceLink,
  forceManyBody,
  forceCenter,
  forceCollide,
} from "d3-force";

const CHARGE_STRENGTH = -300;
const COLLISION_RADIUS = 5;

const simulation = forceSimulation(nodes)
  .force(
    "link",
    forceLink(links)
      .id((d: NodeDatum) => d.id)
      .distance(100),
  )
  .force("charge", forceManyBody().strength(CHARGE_STRENGTH))
  .force("center", forceCenter(width / 2, height / 2))
  .force("collide", forceCollide(COLLISION_RADIUS))
  .on("tick", () => {
    // Update node and link positions from simulation
  });

Why good: named force constants,

.id()

accessor for node identity,

.distance()

for link length, collision prevents overlap

See examples/advanced.md Pattern 1 for complete graph rendering with drag interaction.

Pattern 9: Geographic Projections

Project geographic coordinates onto a 2D plane and render GeoJSON features as SVG paths.

typescript

import { geoMercator, geoPath, geoNaturalEarth1 } from "d3-geo";
import type { GeoPermissibleObjects } from "d3-geo";

const projection = geoNaturalEarth1().fitSize(
  [CHART_WIDTH, CHART_HEIGHT],
  geoJsonData,
);

const pathGenerator = geoPath().projection(projection);

svg
  .selectAll("path")
  .data(geoJsonData.features)
  .join("path")
  .attr("d", pathGenerator)
  .attr("fill", (d) => colorScale(dataByRegion.get(d.properties.id) ?? 0));

Why good:

fitSize

auto-scales projection to container, path generator produces

strings from GeoJSON, color encodes data values per region

See examples/advanced.md Pattern 2 for choropleth maps and interactive tooltips.

Pattern 10: Framework Integration

When using D3 with a component framework, split responsibilities: D3 computes layouts, scales, and shapes; your framework renders the DOM.

typescript

// Pattern: D3 for computation, framework for rendering
// In your component:

const xScale = scaleLinear().domain([0, maxValue]).range([0, width]);
const yScale = scaleBand().domain(labels).range([0, height]).padding(0.1);
const linePath = line<DataPoint>()
  .x((d) => xScale(d.x))
  .y((d) => yScale(d.y)!)(data);

// Your framework renders SVG with computed values
// <svg><path d={linePath} /><rect width={xScale(d.value)} /></svg>

When D3 must own the DOM (zoom, brush, drag, force tick): use a ref to an SVG element and call D3 in a lifecycle hook. Clean up the simulation/behavior on unmount.

See examples/advanced.md Pattern 3 for the ref-based integration pattern and cleanup.

</patterns>

<decision_framework>

Decision Framework

D3 Module Selection

What are you building?
|
+-> Bar/line/area chart?
|   -> d3-selection, d3-scale, d3-axis, d3-shape, d3-array
|
+-> Pie/donut chart?
|   -> d3-shape (pie + arc generators), d3-scale (color)
|
+-> Force-directed graph?
|   -> d3-force, d3-selection, d3-drag
|
+-> Geographic map?
|   -> d3-geo, d3-selection, d3-scale (color)
|
+-> Animated transitions?
|   -> d3-transition, d3-ease, d3-interpolate
|
+-> Interactive (zoom/brush)?
    -> d3-zoom or d3-brush, d3-selection

Framework Integration Strategy

Does the visualization need zoom, brush, drag, or force tick?
|
+-> NO -> D3 for computation only (scales, shapes, layouts)
|         Your framework renders SVG/HTML directly
|         Cleanest integration, fully declarative
|
+-> YES -> D3 owns the SVG via a ref element
           Call D3 in a lifecycle hook (mount/update)
           Clean up behaviors on unmount

Scale Selection

Data Type	Scale	Example
Continuous	scaleLinear	Revenue, temperature
Categorical	scaleBand	Categories on bar chart
Categorical dots	scalePoint	Categories without width
Time series	scaleTime	Dates on x-axis
Logarithmic	scaleLog	Exponential data ranges
Square root	scaleSqrt	Bubble chart radius
Color categories	scaleOrdinal	Category -> color

</decision_framework>

<red_flags>

RED FLAGS

High Priority Issues:

Using
```
import * as d3 from "d3"
```
in production — imports the entire 240KB+ bundle. Use modular imports:
```
import { select } from "d3-selection"
```
Manual enter/append/merge/exit chains — use
```
selection.join()
```
instead (simpler, fewer bugs)
Animating non-interpolable attributes (class names, boolean attributes) — only animate numeric attributes and colors
Missing key function in
```
.data(array, key)
```
when data identity matters — causes incorrect element-data binding on updates
Mutating data arrays bound to selections — D3 stores references; mutations cause stale renders

Medium Priority Issues:

Magic numbers for margins, radii, durations, colors — use named constants
Creating a new SVG on every data update — select the existing SVG, update data bindings
Appending axes on every update (duplicated tick marks) — select existing
```
<g>
```
and
```
.call(axis)
```
again, or use
```
.join()
```
pattern
Forgetting
```
transition.remove()
```
on exit — exiting elements stay in the DOM invisible
Not using
```
.nice()
```
on linear scales — domain ends at awkward values like
```
[0, 473]
```

Gotchas & Edge Cases:

```
selection.join()
```
returns the merged enter+update selection — chained attributes apply to both new and existing elements
```
scaleBand().bandwidth()
```
returns the computed bar width — use it for rect width, not a hardcoded value
```
d3.max()
```
returns
```
undefined
```
for empty arrays — guard with
```
?? 0
```
or check array length first
```
transition.duration()
```
is per-element, not total — a 750ms transition on 100 elements still takes 750ms (not 75,000ms)
```
forceSimulation
```
runs asynchronously via
```
requestAnimationFrame
```
— stop it on unmount to prevent memory leaks
```
geoPath
```
without a projection renders pre-projected coordinates — only omit projection if GeoJSON is already projected
Zoom transform applied to the SVG root clips panned content — apply transform to an inner
```
<g>
```
group instead
```
d3-transition
```
must be imported for
```
selection.transition()
```
to exist — it extends the selection prototype via side effect
```
.datum()
```
binds data to a single element without computing a join — use
```
.data()
```
for arrays,
```
.datum()
```
for single objects

</red_flags>

<critical_reminders>

CRITICAL REMINDERS

All code must follow project conventions in CLAUDE.md

(You MUST use
selection.join()
for data joins — NOT manual enter/append/merge/exit chains)

(You MUST use modular imports (
d3-selection
,
d3-scale
,
d3-shape
) — NOT
import * as d3 from "d3"
in production bundles)

(You MUST use named constants for ALL visual dimensions, colors, and timing values — NO magic numbers)

(You MUST type D3 selections and scales with TypeScript generics —
Selection<SVGGElement, Datum, ...>
,
ScaleLinear<number, number>
)

Failure to follow these rules will cause bloated bundles, incorrect data binding, and untyped visualization code.

</critical_reminders>

web-dataviz-d3

NPX Install

Tags

SKILL.md Content

D3.js Data Visualization Patterns

CRITICAL: Before Using This Skill

Philosophy

Core Patterns

Pattern 1: Selections and the Data Join

Pattern 2: Scales — Mapping Data to Pixels

Pattern 3: Axes — Rendering Scale Tick Marks

Pattern 4: Shape Generators — SVG Paths from Data

Pattern 5: Responsive SVG with viewBox

Pattern 6: Transitions — Animated Data Updates

Pattern 7: Zoom and Pan

Pattern 8: Force-Directed Graph Layout

Pattern 9: Geographic Projections

Pattern 10: Framework Integration

Decision Framework

D3 Module Selection

Framework Integration Strategy

Scale Selection

RED FLAGS

CRITICAL REMINDERS