Skip to content

OrigamChartSankey ​

Sankey diagram family. Visualises flows between categories — energy budgets, revenue funnels, web-traffic paths.

Nodes are inferred automatically from the union of all from and to strings found in series[0].data. Columns are assigned by topological depth (Kahn's algorithm). Flows are rendered as smooth cubic Bezier ribbons whose stroke width is proportional to the flow value.

Use this component when you need to visualise magnitude flows between categorical nodes. Use OrigamChart with type="sankey" when you need runtime switching between chart families.

Import ​

ts
import { OrigamChartSankey } from '@origam/ds'

Quick start ​

vue
<template>
  <origam-chart-sankey
    :series="[{
      name: 'Web funnel',
      data: [
        { from: 'Home', to: 'Catalogue', value: 100 },
        { from: 'Catalogue', to: 'Cart', value: 40 },
        { from: 'Catalogue', to: 'Exit', value: 60 },
        { from: 'Cart', to: 'Checkout', value: 25 },
        { from: 'Checkout', to: 'Success', value: 20 }
      ]
    }]"
    :height="400"
    title="Web funnel"
  />
</template>

<script setup lang="ts">
import { OrigamChartSankey } from '@origam/ds'
</script>

Props ​

Data ​

NameTypeDefaultDescription
seriesArray<IChartSeries>requiredThe Sankey chart reads series[0] only. Each datum in series[0].data must be IChartSankeyDatum — a { from, to, value } triple. Nodes are inferred from the union of all from and to strings.

Visual ​

NameTypeDefaultDescription
heightnumber | string400Chart height. A plain number is px. Ignored when aspectRatio is set.
aspectRatiostringundefinedCSS aspect-ratio shorthand. Overrides height.
colorSchemeArray<TIntent | string>8-intent cyclePalette applied per column index. Nodes in column 0 get colour 0, column 1 gets colour 1, etc. Supports intent names and raw CSS values.
titlestringundefinedOptional title above the chart. Replaceable via the #title slot.
subtitlestringundefinedOptional subtitle below the title.
nodeWidthnumber16Width of each node rectangle in SVG pixels.
nodePaddingnumber8Minimum vertical gap between sibling nodes in the same column, in SVG pixels.
linkOpacitynumber0.4Opacity of the flow ribbons. Range [0, 1].
showLabelbooleantrueWhether to render node name labels. Left-column nodes are right-aligned outside their rect; all other columns are left-aligned outside.

Behaviour ​

NameTypeDefaultDescription
animatedbooleantrueFade nodes and links in on first paint. Respects prefers-reduced-motion.
animationDurationnumber600Animation duration in ms.
showLegendbooleanfalseToggle the legend block. Off by default — Sankey diagrams use node labels instead.
legendPositionTChartLegendPosition'bottom'Legend anchor. One of 'top', 'bottom', 'left', 'right'.
showTooltipbooleantrueToggle the hover tooltip.

Formatting ​

NameTypeDefaultDescription
xAxisFormat(value: number | string) => stringString(value)Applied to node labels and tooltip values.
yAxisFormat(value: number) => stringString(value)Alias for xAxisFormat — kept for API symmetry with other families. yAxisFormat takes precedence.

Emits ​

NamePayloadDescription
point-click(point: IChartPoint, event: MouseEvent | KeyboardEvent)Click or keyboard activation on a node or a link. For nodes point.x is the node name; for links point.x is "from → to".
legend-click(series: IChartSeries, index: number)Click on a legend entry.
series-toggle(series: IChartSeries, visible: boolean)Resulting visibility flip after a legend click.

Slots ​

NameBindingsDescription
node-label{ name: string, value: number, formatted: string, color: string, column: number }Replace the label rendered beside each node.
tooltip{ point: IChartPoint, series: IChartSeries, category: string | number }Replace the default tooltip card.
legend-item{ series: IChartSeries, index: number, visible: boolean }Replace one legend entry.
title—Replace the title + subtitle block.
empty—Rendered when series is empty or no nodes could be derived.

Data shape (IChartSankeyDatum) ​

ts
interface IChartSankeyDatum {
  from: string         // Source node name
  to: string           // Target node name
  value: number        // Flow magnitude (≥ 0)
  color?: TIntent | string  // Optional per-link colour override
}

Behaviour notes ​

Responsive drawing surface (#1324). The SVG viewBox follows the measured box of the chart (useChartSize, a ResizeObserver), not a fixed 600 × 400 canvas. The plot fills the container width and height, the geometry is recomputed, and text, strokes and markers keep their real pixel size instead of being scaled with the viewBox. Until the box is measured (SSR, first paint) the 600 × 400 fallback is used, so hydration is unchanged. Give the chart a height / aspectRatio to change the box ratio.

Single-series only. The component reads series[0] exclusively. Extra series are ignored.

Node inference. Nodes are derived from the union of all from and to strings. You do not declare nodes separately — just provide the links.

Column assignment. Columns are assigned via Kahn's topological sort algorithm. Each node's column = max column of its predecessors + 1. Source nodes (no incoming links) land in column 0.

Cycle detection. If the data contains a directed cycle, the component logs a console warning and renders the reachable acyclic portion. It does not throw.

Node values. Each node's height is proportional to max(sum of incoming links, sum of outgoing links) within its column.

Link ribbons. Each link is rendered as a cubic Bezier <path> from (x_source_right, y_source_band_mid) to (x_target_left, y_target_band_mid). Stroke width is proportional to the link value relative to the source node's total outgoing flow. Stroke colour defaults to the source node's colour; override per-link via datum.color.

Node labels. Left-column nodes (column 0) render their label right-aligned to the left of the node rect. All other nodes render left-aligned to the right. Set showLabel=false to suppress labels entirely.

Empty state. When series is empty or no nodes can be inferred, the #empty slot is rendered instead of the SVG.

Accessibility. Each node <rect> and each link <path> carries role="button" and a descriptive aria-label. The chart is a single tab stop (roving tabindex, #1333): Tab enters it once, the arrow keys move between points, Tab leaves it — see the key table in the OrigamChart page. Arrow keys follow the DOM order: all links first, then all nodes, each in rendering order — there is no geometric navigation. Enter or Space activates the focused element. The SVG carries a <title> and <desc> for screen-reader context.

Accessibility — the <desc> summary is localised AND agrees in number. The <desc> text is not an English literal: it resolves through the DS t() mechanism against origam.chart.sankey.desc*, and the grammatical form is chosen by Intl.PluralRules for the ACTIVE locale — never by a count === 1 test in the component. A translator supplies only the forms their language needs (_one / _other cover en and fr; a Russian translation adds _few with no component change), and a category a locale does not define falls back to _other rather than leaking the raw key. This chart names two independent counts, so each is pluralised as its own fragment and the shell key desc assembles them — that is what keeps the word order, and both agreements, under the translator's control.

Animation. Nodes and links fade in on mount via a CSS keyframe animation. The animation is skipped when animated=false or prefers-reduced-motion: reduce is set.

SSR. The SVG is rendered server-side without JS geometry. There is no onMounted guard — the node and link geometry are pure computed values.

Examples ​

Energy budget ​

vue
<template>
  <origam-chart-sankey
    :series="[{
      name: 'Energy budget',
      data: [
        { from: 'Solar', to: 'Grid', value: 30 },
        { from: 'Wind', to: 'Grid', value: 25 },
        { from: 'Nuclear', to: 'Grid', value: 20 },
        { from: 'Grid', to: 'Residential', value: 35 },
        { from: 'Grid', to: 'Industrial', value: 25 },
        { from: 'Grid', to: 'Commercial', value: 15 }
      ]
    }]"
    :height="400"
    title="Energy budget"
    subtitle="GWh"
  />
</template>

Custom colour ramp + formatted values ​

vue
<template>
  <origam-chart-sankey
    :series="[{
      name: 'Revenue funnel',
      data: [
        { from: 'Leads', to: 'Prospects', value: 5000 },
        { from: 'Prospects', to: 'Demos', value: 1200 },
        { from: 'Demos', to: 'Customers', value: 320 }
      ]
    }]"
    :color-scheme="['#6366f1', '#8b5cf6', '#ec4899']"
    :y-axis-format="(v) => v.toLocaleString()"
    :height="360"
    title="Revenue funnel"
    subtitle="Q2 2026"
  />
</template>