D3.js Data Visualization

Table of Contents

• [Overview](#overview)
• [Workflows](#workflows)

- [Create Basic Chart Workflow](#create-basic-chart-workflow) - [Update Visualization with New Data](#update-visualization-with-new-data) - [Create Advanced Layout Workflow](#create-advanced-layout-workflow)

• [Path Selection Menu](#path-selection-menu)
• [Quick Reference](#quick-reference)

Overview

D3 provides low-level building blocks for data-driven DOM manipulation, visual encoding, layout algorithms, and interactions — enabling bespoke visualizations that chart libraries cannot provide.

Use D3 when: Chart libraries lack your specific design, you need full customization, you're building network graphs/hierarchies/maps, or animating data changes smoothly.

Prefer simpler tools when: Simple bar/line charts suffice (Chart.js, Highcharts), you need 3D (Three.js, WebGL), or datasets exceed 10K points without aggregation.

Core concepts: Data Joins (bind arrays to DOM elements), Scales (data values to visual values), Shapes (SVG path generation), Layouts (position calculation for networks/trees/maps), Transitions (animated state changes), Interactions (zoom/pan/drag/brush).

Skill Structure

• [Getting Started](resources/getting-started.md): Setup, prerequisites, first visualization
• [Selections & Data Joins](resources/selections-datajoins.md): DOM manipulation, data binding
• [Scales & Axes](resources/scales-axes.md): Data transformation, axis generation
• [Shapes & Layouts](resources/shapes-layouts.md): Path generators, basic layouts
• [Advanced Layouts](resources/advanced-layouts.md): Force simulation, hierarchies, geographic maps
• [Transitions & Interactions](resources/transitions-interactions.md): Animations, zoom/pan/drag/brush
• [Workflows](resources/workflows.md): Step-by-step guides for common chart types
• [Common Patterns](resources/common-patterns.md): Reusable code templates

Workflows

Choose a workflow based on your current task:

Create Basic Chart Workflow

Use when: Building bar, line, or scatter charts from scratch

Time: 1-2 hours

Copy this checklist and track your progress:

Basic Chart Progress:
- [ ] Step 1: Set up SVG container with margins
- [ ] Step 2: Load and parse data
- [ ] Step 3: Create scales (x, y)
- [ ] Step 4: Generate axes
- [ ] Step 5: Bind data and create visual elements
- [ ] Step 6: Style and add interactivity

Step 1: Set up SVG container with margins

Create SVG element with proper dimensions. Define margins for axes: {top: 20, right: 20, bottom: 30, left: 40}. Calculate inner width/height: width - margin.left - margin.right. See [Getting Started](resources/getting-started.md#setup-svg-container).

Step 2: Load and parse data

Use d3.csv('data.csv') for external files or define data array directly. Parse dates with d3.timeParse('%Y-%m-%d') for time series. Convert strings to numbers for CSV data using conversion function. See [Getting Started](resources/getting-started.md#loading-data).

Step 3: Create scales

Choose scale types based on data: scaleBand (categorical), scaleTime (temporal), scaleLinear (quantitative). Set domains from data using d3.extent(), d3.max(), or manual ranges. Set ranges from SVG dimensions. See [Scales & Axes](resources/scales-axes.md#scale-types).

Step 4: Generate axes

Create axis generators: d3.axisBottom(xScale), d3.axisLeft(yScale). Append g elements positioned with transforms. Call axis generators: .call(axis). Customize ticks with .ticks(), .tickFormat(). See [Scales & Axes](resources/scales-axes.md#creating-axes).

Step 5: Bind data and create visual elements

Use data join pattern: svg.selectAll(type).data(array).join(type). Set attributes using scales and accessor functions: .attr('x', d => xScale(d.category)). For line charts, use d3.line() generator. For scatter plots, create circles with cx, cy, r attributes. See [Selections & Data Joins](resources/selections-datajoins.md#data-join-pattern) and [Shapes & Layouts](resources/shapes-layouts.md).

Step 6: Style and add interactivity

Apply colors: .attr('fill', ...), .attr('stroke', ...). Add hover effects: .on('mouseover', ...) with tooltip. Add click handlers for drill-down. Apply transitions for initial animation (optional). See [Transitions & Interactions](resources/transitions-interactions.md#tooltips) and [Common Patterns](resources/common-patterns.md#tooltip-pattern).

Update Visualization with New Data

Use when: Refreshing charts with new data (real-time, filters, user interactions)

Time: 30 minutes - 1 hour

Copy this checklist:

Update Progress:
- [ ] Step 1: Encapsulate visualization in update function
- [ ] Step 2: Update scale domains if needed
- [ ] Step 3: Re-bind data with key function
- [ ] Step 4: Add transitions to join
- [ ] Step 5: Update attributes with new values
- [ ] Step 6: Trigger update on data change

Step 1: Encapsulate visualization in update function

Wrap steps 3-5 from basic chart workflow in function update(newData) { ... }. This makes visualization reusable for any dataset. See [Workflows](resources/workflows.md#update-pattern).

Step 2: Update scale domains

Recalculate domains when data range changes: yScale.domain([0, d3.max(newData, d => d.value)]). Update axes with transition: svg.select('.y-axis').transition().duration(500).call(yAxis). See [Selections & Data Joins](resources/selections-datajoins.md#updating-scales).

Step 3: Re-bind data with key function

Use key function for object constancy: .data(newData, d => d.id). Ensures elements track data items, not array positions. Critical for correct transitions. See [Selections & Data Joins](resources/selections-datajoins.md#key-functions).

Step 4: Add transitions to join

Insert .transition().duration(500) before attribute updates. Specify easing with .ease(d3.easeCubicOut). For custom enter/exit effects, use enter/exit functions in .join(). See [Transitions & Interactions](resources/transitions-interactions.md#basic-transitions).

Step 5: Update attributes with new values

Set positions/sizes using updated scales: .attr('y', d => yScale(d.value)), .attr('height', d => height - yScale(d.value)). Transitions animate from old to new values. See [Common Patterns](resources/common-patterns.md#bar-chart-template).

Step 6: Trigger update on data change

Call update(newData) when data changes: button clicks, timers (setInterval), WebSocket messages, API responses. For real-time, use sliding window to limit data points. See [Workflows](resources/workflows.md#real-time-updates).

Create Advanced Layout Workflow

Use when: Building network graphs, hierarchies, or geographic maps

Time: 2-4 hours

Copy this checklist:

Advanced Layout Progress:
- [ ] Step 1: Choose appropriate layout type
- [ ] Step 2: Prepare and structure data
- [ ] Step 3: Create and configure layout
- [ ] Step 4: Apply layout to data
- [ ] Step 5: Bind computed properties to elements
- [ ] Step 6: Add interactions (drag, zoom)

Step 1: Choose appropriate layout type

Force Simulation: Network diagrams, organic clustering. Hierarchies: Tree, cluster (node-link), treemap, pack, partition (space-filling). Geographic: Maps with projections. Chord: Flow diagrams. See [Advanced Layouts](resources/advanced-layouts.md#choosing-layout) for decision guidance.

Step 2: Prepare and structure data

Force: nodes = [{id, group}], links = [{source, target}]. Hierarchy: Nested objects with children arrays, convert with d3.hierarchy(data). Geographic: GeoJSON features. See [Advanced Layouts](resources/advanced-layouts.md#data-structures).

Step 3: Create and configure layout

Force: d3.forceSimulation(nodes).force('link', d3.forceLink(links)).force('charge', d3.forceManyBody()). Hierarchy: d3.treemap().size([width, height]). Geographic: d3.geoMercator().fitExtent([[0,0], [width,height]], geojson). See [Advanced Layouts](resources/advanced-layouts.md) for each layout type.

Step 4: Apply layout to data

Force: Simulation runs automatically, updates node positions each tick. Hierarchy: Call layout on root: treemap(root). Geographic: No application needed, projection used in path generator. See [Advanced Layouts](resources/advanced-layouts.md#applying-layouts).

Step 5: Bind computed properties to elements

Force: Update cx, cy in tick handler: node.attr('cx', d => d.x). Hierarchy: Use d.x0, d.x1, d.y0, d.y1 for rectangles. Geographic: Use path(feature) for d attribute. See [Workflows](resources/workflows.md) for layout-specific examples.

Step 6: Add interactions

Drag for force networks: node.call(d3.drag().on('drag', dragHandler)). Zoom for maps/large networks: svg.call(d3.zoom().on('zoom', zoomHandler)). Click for hierarchy drill-down. See [Transitions & Interactions](resources/transitions-interactions.md).

Path Selection Menu

What would you like to do?

1. [I'm new to D3](resources/getting-started.md) - Setup environment, understand prerequisites, create first visualization

1. [Build a basic chart](resources/workflows.md#basic-charts) - Bar, line, or scatter plot step-by-step

1. [Transform data with scales](resources/scales-axes.md) - Map data values to visual properties (positions, colors, sizes)

1. [Bind data to elements](resources/selections-datajoins.md) - Connect arrays to DOM elements, handle dynamic updates

1. [Create network/hierarchy/map](resources/advanced-layouts.md) - Force-directed graphs, treemaps, geographic visualizations

1. [Add animations](resources/transitions-interactions.md#transitions) - Smooth transitions between chart states

1. [Add interactivity](resources/transitions-interactions.md#interactions) - Zoom, pan, drag, brush selection, tooltips

1. [Update chart with new data](resources/workflows.md#update-pattern) - Handle real-time data, filters, user interactions

1. [Get code templates](resources/common-patterns.md) - Copy-paste-modify templates for common patterns

1. [Understand D3 concepts](resources/getting-started.md#core-concepts) - Deep dive into data joins, scales, generators, layouts

Quick Reference

Data Join Pattern (Core D3 Workflow)

// 1. Select container
const svg = d3.select('svg');

// 2. Bind data
svg.selectAll('circle')
  .data(dataArray)
  .join('circle')          // Create/update/remove elements automatically
    .attr('cx', d => d.x)  // Use accessor functions (d = datum, i = index)
    .attr('cy', d => d.y)
    .attr('r', 5);

Scale Creation (Data → Visual Transformation)

// For quantitative data
const xScale = d3.scaleLinear()
  .domain([0, 100])        // Data range
  .range([0, 500]);        // Pixel range

// For categorical data
const xScale = d3.scaleBand()
  .domain(['A', 'B', 'C'])
  .range([0, 500])
  .padding(0.1);

// For temporal data
const xScale = d3.scaleTime()
  .domain([new Date(2020, 0, 1), new Date(2020, 11, 31)])
  .range([0, 500]);

Shape Generators (SVG Path Creation)

// Line chart
const line = d3.line()
  .x(d => xScale(d.date))
  .y(d => yScale(d.value));

svg.append('path')
  .datum(data)           // Use .datum() for single data item
  .attr('d', line)       // Line generator creates path data
  .attr('fill', 'none')
  .attr('stroke', 'steelblue');

Transitions (Animation)

// Add transition before attribute updates
svg.selectAll('rect')
  .data(newData)
  .join('rect')
  .transition()          // Everything after this is animated
  .duration(500)         // Milliseconds
  .attr('height', d => yScale(d.value));

Common Scale Types

D3 Module Imports (ES6)

// Specific functions
import { select, selectAll } from 'd3-selection';
import { scaleLinear, scaleBand } from 'd3-scale';
import { line, area } from 'd3-shape';

// Entire D3 namespace
import * as d3 from 'd3';

Key Resources by Task

• Setup & First Chart: [Getting Started](resources/getting-started.md)
• Data Binding: [Selections & Data Joins](resources/selections-datajoins.md)
• Scales & Axes: [Scales & Axes](resources/scales-axes.md)
• Chart Types: [Workflows](resources/workflows.md) + [Common Patterns](resources/common-patterns.md)
• Networks & Trees: [Advanced Layouts](resources/advanced-layouts.md#force-simulation) + [Advanced Layouts](resources/advanced-layouts.md#hierarchies)
• Maps: [Advanced Layouts](resources/advanced-layouts.md#geographic-maps)
• Animation: [Transitions & Interactions](resources/transitions-interactions.md#transitions)
• Interactivity: [Transitions & Interactions](resources/transitions-interactions.md#interactions)

Next Steps

1. New to D3? Start with [Getting Started](resources/getting-started.md)
2. Know basics? Jump to [Workflows](resources/workflows.md) for specific chart types
3. Need reference? Use [Common Patterns](resources/common-patterns.md) for templates
4. Build custom viz? Explore [Advanced Layouts](resources/advanced-layouts.md)