FlowStory
A scripted, sequenced, looping flow animation — walks a graph step by step with fade-in captions.
Category: display · WCAG 2.1-AA · flow, animation, storyline, walkthrough, sequence
States
- playing
- paused
Props
| Prop | Type | Default | Description |
|---|---|---|---|
nodes | FlowNode[] | — | The nodes to render. |
edges | FlowEdge[] | — | The edges to render at each step. |
script | StoryStep[] | — | Ordered steps: { from, to, label? } or { edge, reverse? }. |
loop | boolean | true | When true, navigation wraps around from end to start. |
stepDuration | number | 1500 | How long (ms) each step is shown during playback. |
stepGap | number | 0 | Extra pause after each step before advancing (ms) — makes the story easier to follow. |
playing | boolean | — | Whether the story is currently playing (controlled). |
currentStep | number | — | The controlled current step index. |
onStepChange | (step: number) => void | — | Called with the new step index when it changes. |
controls | boolean | true | Whether to show the controls. |
autoPlay | boolean | true | When true, starts playback automatically on mount. |
interactive | boolean | false | A storyline is a view by default — set true to allow selecting/dragging/connecting. |
className | string | — | Additional CSS class names merged onto the root element. |
background | boolean | true | Render the dotted background pane behind the flow. |
clock | StoryClock | — | Injectable clock for deterministic tests. |
labels | FlowStoryLabels | — | Label overrides for the story playback controls. |
Design tokens
--cascivo-color-surface--cascivo-color-accent--cascivo-color-text-muted
When to use
- Explaining how a flow works step by step, not just showing a static diagram
- Onboarding, architecture walkthroughs, and request/response narratives
When not to use
- A static or freely-explorable graph — use <Flow>
- A single always-on animated edge — set animated on a FlowEdge
Examples
A request/response storyboard
A<->B-->C: animate A→B, B→A, A→B, B→C, looping — each step fades in its caption.
() => (
<FlowStory
style={{ height: 340 }}
nodes={[
{ id: 'A', position: { x: 0, y: 100 }, data: { label: 'Client' } },
{ id: 'B', position: { x: 240, y: 100 }, data: { label: 'Gateway' } },
{ id: 'C', position: { x: 480, y: 100 }, data: { label: 'Service' } },
]}
edges={[
{ id: 'ab', source: 'A', target: 'B' },
{ id: 'bc', source: 'B', target: 'C' },
]}
script={[
{ from: 'A', to: 'B', label: 'Request sent' },
{ from: 'B', to: 'A', label: 'Acknowledged' },
{ from: 'A', to: 'B', label: 'Payload streamed' },
{ from: 'B', to: 'C', label: 'Forwarded to Service' },
]}
loop
/>
)A linear pipeline
Each stage animates and is captioned in turn.
() => (
<FlowStory
style={{ height: 320 }}
nodes={[
{ id: 'ingest', position: { x: 0, y: 100 }, data: { label: 'Ingest' } },
{ id: 'transform', position: { x: 240, y: 100 }, data: { label: 'Transform' } },
{ id: 'load', position: { x: 480, y: 100 }, data: { label: 'Load' } },
]}
edges={[
{ id: 'it', source: 'ingest', target: 'transform' },
{ id: 'tl', source: 'transform', target: 'load' },
]}
script={[
{ from: 'ingest', to: 'transform', label: 'Records ingested', description: 'Raw events read from the source' },
{ from: 'transform', to: 'load', label: 'Transformed', description: 'Cleaned and enriched' },
]}
/>
)