version: "1.0.1" name: d3-visualization description: Guides creation of custom, interactive data visualizations with D3.js — bar/line/scatter charts, network diagrams, geographic maps, hierarchies, and real-time data updates with zoom/pan/brush interactions and animated transitions. Use when chart libraries (Highcharts, Chart.js) lack the customization needed and you require low-level control over data-driven DOM manipulation, scales, shapes, and layouts. Invoke when user mentions D3, d3.js, custom visualization, force-directed graph, or data-driven SVG.

D3.js Data Visualization

Table of Contents

• Overview
• Workflows
• Create Basic Chart Workflow
• Update Visualization with New Data
• Create Advanced Layout Workflow
• Path Selection Menu
• 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.

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.

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.

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.

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 and Shapes & Layouts.

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 and Common Patterns.

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.

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.

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.

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.

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.

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.

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 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.

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 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.

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 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.

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
• Data Binding: Selections & Data Joins
• Scales & Axes: Scales & Axes
• Chart Types: Workflows + Common Patterns
• Networks & Trees: Advanced Layouts + Advanced Layouts
• Maps: Advanced Layouts
• Animation: Transitions & Interactions
• Interactivity: Transitions & Interactions

Next Steps

1. New to D3? Start with Getting Started
2. Know basics? Jump to Workflows for specific chart types
3. Need reference? Use Common Patterns for templates
4. Build custom viz? Explore Advanced Layouts