Sankey Diagrams for Flow Visualization on Website

Sankey Diagram Development for Flow Visualization

A Sankey diagram shows flows between nodes: band width is proportional to flow volume. One of the best tools for questions like "where did money come from and where did it go," "how do users move through funnel stages," "which pages are traffic sources for which conversions."

Without a specialized tool, building Sankey manually is difficult—you need a layout algorithm that places nodes correctly and draws Bezier curves. The d3-sankey library handles this.

Installation

npm install d3-sankey d3
npm install --save-dev @types/d3-sankey

Data Structure

interface SankeyNode {
  id: string;
  label: string;
  color?: string;
}

interface SankeyLink {
  source: string;  // source node id
  target: string;  // target node id
  value: number;   // flow volume
}

interface SankeyData {
  nodes: SankeyNode[];
  links: SankeyLink[];
}

// Example: e-commerce funnel
const data: SankeyData = {
  nodes: [
    { id: 'organic', label: 'Organic' },
    { id: 'paid', label: 'Paid Ads' },
    { id: 'direct', label: 'Direct' },
    { id: 'catalog', label: 'Catalog' },
    { id: 'product', label: 'Product Card' },
    { id: 'cart', label: 'Cart' },
    { id: 'checkout', label: 'Checkout' },
    { id: 'purchase', label: 'Purchase' },
    { id: 'exit', label: 'Exit' },
  ],
  links: [
    { source: 'organic', target: 'catalog', value: 4200 },
    { source: 'organic', target: 'product', value: 1800 },
    { source: 'paid', target: 'catalog', value: 2100 },
    { source: 'paid', target: 'product', value: 3400 },
    { source: 'direct', target: 'catalog', value: 900 },
    { source: 'catalog', target: 'product', value: 5600 },
    { source: 'catalog', target: 'exit', value: 3100 },
    { source: 'product', target: 'cart', value: 2900 },
    { source: 'product', target: 'exit', value: 4800 },
    { source: 'cart', target: 'checkout', value: 1600 },
    { source: 'cart', target: 'exit', value: 1300 },
    { source: 'checkout', target: 'purchase', value: 1100 },
    { source: 'checkout', target: 'exit', value: 500 },
  ],
};

Component

import { useEffect, useRef } from 'react';
import * as d3 from 'd3';
import { sankey, sankeyLinkHorizontal, sankeyLeft } from 'd3-sankey';

export function SankeyDiagram({ data, width = 800, height = 500 }: { data: SankeyData; width?: number; height?: number }) {
  const svgRef = useRef<SVGSVGElement>(null);
  const margin = { top: 20, right: 20, bottom: 20, left: 20 };

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

    const svg = d3.select(svgRef.current);
    svg.selectAll('*').remove();

    const iw = width - margin.left - margin.right;
    const ih = height - margin.top - margin.bottom;

    // Prepare data for d3-sankey
    const nodeMap = new Map(data.nodes.map((n, i) => [n.id, { ...n, index: i }]));

    const sankeyData = {
      nodes: data.nodes.map(n => ({ ...n })),
      links: data.links.map(l => ({
        source: data.nodes.findIndex(n => n.id === l.source),
        target: data.nodes.findIndex(n => n.id === l.target),
        value: l.value,
      })),
    };

    const sankeyLayout = sankey()
      .nodeWidth(20)
      .nodePadding(12)
      .nodeAlign(sankeyLeft)
      .extent([[0, 0], [iw, ih]]);

    const { nodes, links } = sankeyLayout(sankeyData as any);

    const colorScale = d3.scaleOrdinal(d3.schemeTableau10);

    const g = svg.append('g').attr('transform', `translate(${margin.left},${margin.top})`);

    // Tooltip
    const tooltip = d3.select('body').append('div')
      .style('position', 'absolute')
      .style('display', 'none')
      .style('background', 'rgba(0,0,0,0.8)')
      .style('color', '#fff')
      .style('padding', '8px 12px')
      .style('border-radius', '4px')
      .style('font-size', '13px')
      .style('pointer-events', 'none');

    // Links
    g.append('g')
      .selectAll('.link')
      .data(links)
      .join('path')
      .attr('class', 'link')
      .attr('d', sankeyLinkHorizontal())
      .attr('fill', 'none')
      .attr('stroke', (d: any) => colorScale(String(d.source.index)))
      .attr('stroke-width', (d: any) => Math.max(1, d.width))
      .attr('stroke-opacity', 0.4)
      .on('mouseover', (event, d: any) => {
        d3.select(event.currentTarget).attr('stroke-opacity', 0.7);
        tooltip
          .style('display', 'block')
          .style('left', `${event.pageX + 12}px`)
          .style('top', `${event.pageY - 28}px`)
          .html(`<strong>${d.source.label} → ${d.target.label}</strong><br/>${d3.format(',.0f')(d.value)} users`);
      })
      .on('mouseout', (event) => {
        d3.select(event.currentTarget).attr('stroke-opacity', 0.4);
        tooltip.style('display', 'none');
      });

    // Nodes
    const nodeG = g.append('g')
      .selectAll('.node')
      .data(nodes)
      .join('g')
      .attr('class', 'node');

    nodeG.append('rect')
      .attr('x', (d: any) => d.x0)
      .attr('y', (d: any) => d.y0)
      .attr('width', (d: any) => d.x1 - d.x0)
      .attr('height', (d: any) => Math.max(1, d.y1 - d.y0))
      .attr('fill', (d: any) => colorScale(String(d.index)))
      .attr('rx', 3)
      .on('mouseover', (event, d: any) => {
        tooltip
          .style('display', 'block')
          .style('left', `${event.pageX + 12}px`)
          .style('top', `${event.pageY - 28}px`)
          .html(`<strong>${d.label}</strong><br/>Volume: ${d3.format(',.0f')(d.value)}`);
      })
      .on('mouseout', () => tooltip.style('display', 'none'));

    // Labels
    nodeG.append('text')
      .attr('x', (d: any) => d.x0 < iw / 2 ? d.x1 + 6 : d.x0 - 6)
      .attr('y', (d: any) => (d.y0 + d.y1) / 2)
      .attr('dy', '0.35em')
      .attr('text-anchor', (d: any) => d.x0 < iw / 2 ? 'start' : 'end')
      .attr('font-size', 12)
      .attr('fill', '#374151')
      .text((d: any) => d.label);

    return () => { tooltip.remove(); };
  }, [data, width, height]);

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

Server-Side Data Preparation

Sankey data is usually aggregated from an event stream. Example for site funnel:

-- Sequential page transitions within sessions
WITH ranked_events AS (
  SELECT
    session_id,
    page_type,
    LAG(page_type) OVER (PARTITION BY session_id ORDER BY created_at) AS prev_page_type,
    ROW_NUMBER() OVER (PARTITION BY session_id ORDER BY created_at) AS step
  FROM page_views
  WHERE created_at > NOW() - INTERVAL '30 days'
)
SELECT
  COALESCE(prev_page_type, 'entry') AS source,
  page_type AS target,
  COUNT(*) AS value
FROM ranked_events
WHERE prev_page_type IS NOT NULL OR step = 1
GROUP BY 1, 2
HAVING COUNT(*) > 50  -- filter rare transitions
ORDER BY value DESC;

Layout Nuances

d3-sankey supports several node alignment algorithms:

• sankeyLeft—nodes align to level left edge. Good for funnels
• sankeyRight—to right edge
• sankeyCenter—to graph center (for acyclic graphs)
• sankeyJustify (default)—leaf nodes pushed to right edge

For cyclic data (A → B → A) standard d3-sankey doesn't work—preprocessing or d3-sankey-circular library needed.

Timeline

Sankey diagram with tooltip and basic interactions—2–3 days. With drill-down (node click reveals details), period filtering, and export—5–7 days.