Journey

A journey lists steps in order. Each step has a score from 1 to 5, drawn as a face on a five-step scale. Sections group the steps. Actors are chips on the step and across the top.

When to use it

Use a journey when the question is how a step felt, and who was in it. Checkout is smooth until payment: a declined card scores 1, then confirmation recovers. Paper Kite playtest and First note are the same shape for a game and a notebook.

A funnel is a count at each stage. The width is how many remain. A journey score is not a count. A low score is a painful step, not a smaller population. A timeline places events on dates. Journey steps have no dates. The order is the row order.

Journey, funnel, and timeline

All three can show a sequence. The value is what changes.

type: "journey" maps score to a face. 1 and 2 use the negative color. 3 uses muted. 4 and 5 use the positive color. The other marks on the scale stay as small dots.

type: "funnel" maps a count to the width. Visit, signup, pay is that chart. Do not put a satisfaction score in a funnel, and do not put a headcount in a journey.

type: "timeline" needs a date. A journey does not. If the question is when the step happened, use a timeline.

Data

Each row is one step. section groups the rows. step is the label. score is an integer from 1 to 5. actors is a comma-separated list. Checkout uses Shopper, then Shopper, Payments, then Shopper, Payments, Support.

encoding.x is the step, encoding.y is the score, encoding.series is the section, and encoding.color can name the actor field. The defaults are step, score, section, and actors, so a small spec can omit encoding. A column named actors is read even when encoding.color is omitted.

The chips are drawn from that field. They are not a legend. legend does not place them or hide them. A missing section is CK1410. A missing score, or a score outside 1..5, is CK1409. Both come from validatePhase4.

a11y.alt is required. One sentence, 10 to 500 characters, with the point of the chart.

one step
{
  "section": "Pay",
  "step": "Fix a declined card",
  "score": 1,
  "actors": "Shopper, Payments, Support"
}

A spec that renders

This is the smallest journey. version, type, and a11y.alt are required. One section, Pay. One step, Card, scoring 2, with one actor. The face sits on 2. The other four marks stay empty.

The chart loads from @chartkitdev/core/charts/journey, or from @chartkitdev/core/extra. It is not in the line bundle. validate() warns CK1011 and points at validatePhase4(). user-journey repairs to journey.

spec.json
{
  "version": "1",
  "type": "journey",
  "data": [
    {
      "section": "Pay",
      "step": "Card",
      "score": 2,
      "actors": "Shop"
    }
  ],
  "a11y": {
    "alt": "Card scores 2."
  }
}

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/journeyBundle@chartkitdev/core/extraFamilyPlanning
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;

The 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 journey specs. Checkout is the core example, nine steps from browse to tracking the parcel. Paper Kite playtest is the showcase chart from a Mermaid journey. First note is the discovery chart. The spec has no title, so the switcher uses the showcase heading.

Tooltip

tooltip is on for a journey when the key is omitted. Hovering a face shows the step, the score out of 5, and the actors on that step. The same sentence is the SVG title. tooltip: false tells the hover card not to open. tooltip: true turns it on.

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

tooltip.fields is not read. The card is the mark label, not a field table. Turning the card off and on again puts a custom tooltip object back in the spec. The card still uses the mark label.

The rest of the spec

There is no mark key for the face, the 1–5 scale, or the chips. The score is the row. legend does not restyle the actors. Theme presets live on the playground.