Streamgraph

A streamgraph stacks several series into one shape, then moves the baseline so the layers sit around a center instead of on zero. The type is streamgraph. The baseline is not zero unless you ask for it.

When to use it

Use a streamgraph when the series are parts of a whole over an ordered x, and the question is how the layers change, not the total against zero. Copies by genre is that chart: history overtakes fiction, and the shape follows the movement. Use center when you want each column centered. Use expand when the question is the share. Weekly streams is a share.

Do not use it when the reader needs the total on a baseline. That is a stacked area. Do not use it for one series. A single layer repairs toward a zero baseline. A filled line is still a line.

Streamgraph, stacked area, and a filled line

A stacked area anchors the stack to zero. The top edge is the total. mark.stack set to percent turns each x into 100% and still sits on that baseline.

A streamgraph's offset is the stack. wiggle is the default. It shifts the baseline so the layers move less from one x to the next. center, also called silhouette, centers each column on zero. zero is the stacked-area baseline, on this type. expand draws shares that sum to 1.

A filled line is not either chart. There is no type: "area". Area is the note for type: "line" with mark.area set to true. Those fills are not stacked.

filled line
{
  "type": "line",
  "mark": { "area": true }
}

mark.stack on a streamgraph warns, and repair removes it. The key is mark.streamOffset.

Data

The rows match a stacked area. Wide data uses encoding.x and a list of encoding.y fields. Copies by genre lists fiction, history, poetry, and science. Weekly streams lists audio and video. Long data uses one encoding.y field and encoding.color, or encoding.series, for the layer name. Centered genres is long: year, copies, and genre.

The numbers are amounts, and they are not negative. A negative is an error. You do not pass shares unless you set expand, which turns each x into a share from the amounts you did pass. a11y.alt is required. One sentence, 10 to 500 characters. Say which layer grew and which shrank. Do not claim the picture shows a total against zero, unless the offset is zero.

A spec that renders

This is the smallest streamgraph. version, type, and a11y.alt are required. Two genres, three years. The offset is wiggle, the order is inside-out, and the curve is monotone, so mark can be omitted. The baseline is not zero.

spec.json
{
  "version": "1",
  "type": "streamgraph",
  "data": [
    {
      "year": "2020",
      "fiction": 20,
      "history": 12
    },
    {
      "year": "2021",
      "fiction": 28,
      "history": 18
    },
    {
      "year": "2022",
      "fiction": 22,
      "history": 30
    }
  ],
  "encoding": {
    "x": "year",
    "y": [
      "fiction",
      "history"
    ]
  },
  "a11y": {
    "alt": "History overtook fiction by 2022. The baseline is not zero."
  }
}

Install core and the adapter for your framework. The menu in the sidebar picks the snippet. spec is the JSON above.

Import@chartkitdev/core/charts/streamgraphBundle@chartkitdev/core/extraFamilyLibrary
React
npm install @chartkitdev/core
npm install @chartkitdev/react

import { Chart } from "@chartkitdev/react";

export function Panel() {
  return <Chart spec={spec} />;
}
Vanilla
npm install @chartkitdev/core
npm install @chartkitdev/vanilla

import { mount } from "@chartkitdev/vanilla";

const chart = mount(document.querySelector("#chart"), spec);
chart.update(spec);
Vue
npm install @chartkitdev/core
npm install @chartkitdev/vue

<script setup>
import { Chart } from "@chartkitdev/vue";
</script>

<template>
  <Chart :spec="spec" />
</template>
Svelte
npm install @chartkitdev/core
npm install @chartkitdev/svelte

<script>
  import { Chart } from "@chartkitdev/svelte";
</script>

<Chart {spec} />
Astro
npm install @chartkitdev/core
npm install @chartkitdev/astro

---
import { Chart } from "@chartkitdev/astro";
---

<Chart spec={spec} />
Solid
npm install @chartkitdev/core
npm install @chartkitdev/solid

import { Chart } from "@chartkitdev/solid";

export function Panel() {
  return <Chart spec={spec} />;
}
Qwik
npm install @chartkitdev/core
npm install @chartkitdev/qwik

import { component$ } from "@builder.io/qwik";
import { Chart } from "@chartkitdev/qwik";

export const Panel = component$(() => {
  return <Chart spec={spec} />;
});
Angular
npm install @chartkitdev/core
npm install @chartkitdev/angular

import { Component } from "@angular/core";
import { Chart } from "@chartkitdev/angular";

@Component({
  standalone: true,
  imports: [Chart],
  template: `<ck-chart [spec]="spec" />`,
})
export class Panel {
  spec = spec;
}
Custom element
npm install @chartkitdev/core
npm install @chartkitdev/element

import "@chartkitdev/element";

const chart = document.querySelector("chart-kit");
chart.spec = spec;

Each option below is a key on the spec. The demo changes that key and updates the chart and the snippet together.

Examples

The rail switches among existing streamgraph specs. Copies by genre is the wiggle chart, with the series name on the layer. Centered genres is long data, centered, with the legend on the right. Weekly streams sets expand on a time axis. The gallery calls that third chart Weekly share.

Offset

mark.streamOffset is the baseline. Omit it, or set wiggle, and the baseline moves to keep the layers smooth. That is the streamgraph. center centers each column. silhouette is the same picture. The control writes center.

zero stacks on the axis. The top edge is the total, which is the stacked-area reading, still as type: "streamgraph". expand turns each column into shares. Weekly streams sets that. The y axis is then a percent.

mark.streamOffset
{
  "mark": { "streamOffset": "center" }
}
mark.streamOffset zero
{
  "mark": { "streamOffset": "zero" }
}

Order

mark.order is the layer order. Omit it on a wiggle chart and the order is inside-out: the smallest series sits in the middle, which keeps the shape calm. Omit it on any other offset and the order is the order the fields are listed.

none keeps that listed order even on a wiggle chart, so the legend matches the fields you wrote. Centered genres sets it. ascending and descending sort by the series sum.

mark.order
{
  "mark": { "order": "none" }
}

Curve

mark.curve is how the edges join, the same choice as a stacked area. monotone is the default. It stays inside the data, so a spike does not overshoot. linear draws straight segments. step holds the value and then jumps.

mark.curve
{
  "mark": { "curve": "linear" }
}

step-before and step-after place the jump on the other side of the point. Set those in the playground.

Legend

A streamgraph with several series shows a legend. Omit legend, or set true, and it sits on top. false hides it. legend.position is top, right, bottom, left, or inside. Centered genres puts it on the right.

legend.position
{
  "legend": { "position": "right" }
}

Tooltip

tooltip is on for a streamgraph when the key is omitted. Hovering a position shows the layer values. The numbers are the amounts you passed, not the offset coordinate. tooltip: false turns the card off. tooltip: true turns it on.

tooltip false
{
  "tooltip": false
}
tooltip true
{
  "tooltip": true
}

tooltip.fields chooses the rows, and tooltip.position places the card. Change those in the playground. Turning the card off and on again puts that object back.

The rest of the spec

mark.labels draws the series name at the thickest part of a layer. It is off until you set true. Copies by genre and Weekly streams set it. mark.fillOpacity defaults to 0.22. The stroke stays the series color. Theme presets live on the playground, with the full option list.