Skill v1.0.1
currentAutomated scan100/1001 files
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?
- [I'm new to D3](resources/getting-started.md) - Setup environment, understand prerequisites, create first visualization
- [Build a basic chart](resources/workflows.md#basic-charts) - Bar, line, or scatter plot step-by-step
- [Transform data with scales](resources/scales-axes.md) - Map data values to visual properties (positions, colors, sizes)
- [Bind data to elements](resources/selections-datajoins.md) - Connect arrays to DOM elements, handle dynamic updates
- [Create network/hierarchy/map](resources/advanced-layouts.md) - Force-directed graphs, treemaps, geographic visualizations
- [Add animations](resources/transitions-interactions.md#transitions) - Smooth transitions between chart states
- [Add interactivity](resources/transitions-interactions.md#interactions) - Zoom, pan, drag, brush selection, tooltips
- [Update chart with new data](resources/workflows.md#update-pattern) - Handle real-time data, filters, user interactions
- [Get code templates](resources/common-patterns.md) - Copy-paste-modify templates for common patterns
- [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 containerconst svg = d3.select('svg');// 2. Bind datasvg.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 dataconst xScale = d3.scaleLinear().domain([0, 100]) // Data range.range([0, 500]); // Pixel range// For categorical dataconst xScale = d3.scaleBand().domain(['A', 'B', 'C']).range([0, 500]).padding(0.1);// For temporal dataconst xScale = d3.scaleTime().domain([new Date(2020, 0, 1), new Date(2020, 11, 31)]).range([0, 500]);
Shape Generators (SVG Path Creation)
// Line chartconst 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 updatessvg.selectAll('rect').data(newData).join('rect').transition() // Everything after this is animated.duration(500) // Milliseconds.attr('height', d => yScale(d.value));
Common Scale Types
| Data Type | Task | Scale | |
|---|---|---|---|
| Quantitative (linear) | Position, size | scaleLinear() | |
| Quantitative (exponential) | Compress range | scaleLog(), scalePow() | |
| Quantitative → Circle area | Size circles | scaleSqrt() | |
| Categorical | Bars, groups | scaleBand(), scalePoint() | |
| Categorical → Colors | Color encoding | scaleOrdinal() | |
| Temporal | Time series | scaleTime() | |
| Quantitative → Colors | Heatmaps | scaleSequential() |
D3 Module Imports (ES6)
// Specific functionsimport { select, selectAll } from 'd3-selection';import { scaleLinear, scaleBand } from 'd3-scale';import { line, area } from 'd3-shape';// Entire D3 namespaceimport * 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
- New to D3? Start with Getting Started
- Know basics? Jump to Workflows for specific chart types
- Need reference? Use Common Patterns for templates
- Build custom viz? Explore Advanced Layouts