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.
{
"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.
{
"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.
npm install @chartkitdev/core
npm install @chartkitdev/react
import { Chart } from "@chartkitdev/react";
export function Panel() {
return <Chart spec={spec} />;
}npm install @chartkitdev/core
npm install @chartkitdev/vanilla
import { mount } from "@chartkitdev/vanilla";
const chart = mount(document.querySelector("#chart"), spec);
chart.update(spec);npm install @chartkitdev/core
npm install @chartkitdev/vue
<script setup>
import { Chart } from "@chartkitdev/vue";
</script>
<template>
<Chart :spec="spec" />
</template>npm install @chartkitdev/core
npm install @chartkitdev/svelte
<script>
import { Chart } from "@chartkitdev/svelte";
</script>
<Chart {spec} />npm install @chartkitdev/core
npm install @chartkitdev/astro
---
import { Chart } from "@chartkitdev/astro";
---
<Chart spec={spec} />npm install @chartkitdev/core
npm install @chartkitdev/solid
import { Chart } from "@chartkitdev/solid";
export function Panel() {
return <Chart spec={spec} />;
}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} />;
});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;
}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": 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.