Timeline block

The timeline: block is the only syntax Siren adds on top of Mermaid. It comes after the diagram body and describes how the picture changes each time Next is pressed. A document can also hold several named blocks, timeline <name>:, so that one diagram tells more than one story; see Several timelines in one document.

flowchart LR
  A[Plan] --> B[Build]
  B --> C[Review]
  C --> D[Ship]

timeline:
  enter B fade, enter A-B fade
  enter C fade, enter B-C fade
  enter D fade, enter C-D fade
  highlight B outline
  highlight D glow, unhighlight B
  exit B slide-left, exit A-B slide-left, exit B-C slide-left, unhighlight D
  exit C-D slide-top

Syntax

timeline:
  <action>, <action>, ...
  <action>, ...
  • Header: timeline:, or timeline <name>: for a named block. All lowercase, one space before the name, nothing between the name and the colon, and nothing after the colon. It may be indented. Any other line that starts with timeline is not a header and keeps its ordinary meaning.
  • Position: after the diagram body. Everything from the first timeline header to the end of the file is timeline, so no diagram syntax can follow it. A document has either one unnamed timeline: or named blocks, never both, and the unnamed one cannot appear twice.
  • One line is one step: the first line is step 1, the second line is step 2, and so on. You don’t write step numbers, and you can’t.
  • A step can hold several actions, separated by commas and applied in written order. No trailing comma.
  • Each action is verb target [effect], separated by spaces. An action names exactly one target; there is no all and no wildcard.
  • Indentation doesn’t matter; %% comments can go anywhere in a timeline block, unlike in the diagram body, where only a whole line is a comment. The one exception is a flowchart target that itself begins with %% (A --> %%B draws a node %%B): a %% glued to the start of the target is the id’s, so enter %%B fade reaches it. Write %% note, with a space, for a comment.
  • Verbs and effects are case-sensitive.

How steps are counted

  • A step’s number is the line’s position in the block, counting from 1; the total number of steps is the number of non-blank lines.
  • Blank lines are not steps, so you can use them to split a long timeline into sections. A line holding only a %% comment counts as blank.
  • A malformed line still takes a step number. The line reports an error and the document is not drawn, but the lines after it keep their numbers, and fixing it renumbers nothing. The at step N in an error message is the Nth non-blank line from the top.
  • To insert a step, just add a line in the middle; the lines after it move down on their own.
  • Prev jumps straight back to the previous step’s state without playing the animation in reverse; Reset goes back to step 0 (not started).
flowchart LR
  A --> B --> C

timeline:
  %% First, B enters
  enter B fade, enter A-B fade

  %% Then C enters and is highlighted
  enter C fade, enter B-C fade
  highlight C glow

The timeline above has three steps: the two comment lines and the blank line between them do not count.

Older versions of Siren wrote step 1: enter B fade; that prefix is gone. Writing step 1: now reports Unrecognized timeline action; just delete the step N:.

Actions and effects

Verb Effect (required) Description
enter fade, slide-left, slide-right, slide-top, slide-bottom The element appears at this step. Before that it is invisible but still takes up its space.
exit fade, slide-left, slide-right, slide-top, slide-bottom The element disappears at this step. Its space is kept, and nothing else is re-laid out.
highlight outline, glow Highlights the element. Highlighting the same element again replaces the previous highlight rather than stacking on it.
unhighlight No effect Removes the highlight. No error if the element was not highlighted.

enter, exit and highlight must name an effect; there is no default. unhighlight cannot take one.

What the effects look like

Effect Animation Duration
fade Fades in / out 600ms
slide-left enter: slides in from 60px to the left; exit: slides out to the left 500ms
slide-right enter: slides in from the right; exit: slides out to the right 500ms
slide-top enter: slides in from above; exit: slides out upward 500ms
slide-bottom enter: slides in from below; exit: slides out downward 500ms
outline The outline turns the highlight color and gets thicker 300ms
glow The element glows 300ms

Durations, distance and the highlight color are design tokens you can tune: --siren-fade-duration, --siren-slide-duration, --siren-slide-distance, --siren-highlight-duration, --siren-highlight-color, --siren-highlight-stroke-width. See Themes.

outline and glow both work on every element of every diagram type, and always win over an author’s stroke: while the element is highlighted its border is drawn in the highlight color even if the document styled it (style A stroke:#f00), and the author’s color comes back afterwards. A flowchart edge’s arrowhead follows its line, so it is highlighted with it. An invisible flowchart edge (A ~~~ B) stays invisible under a highlight; make it visible with linkStyle, not with the timeline.

Target ids

Targets are named by id, and the rules differ by diagram. The common pattern:

  • Elements the author names (nodes, classes, participants, states, entities, gantt tasks) use that name. A gantt task written without an id is task1, task2, …, as in Mermaid.
  • Connections (edges, relationships, messages, transitions) use from-to. From the second occurrence of the same pair on, write A-B#2, A-B#3, numbered in order of appearance. Direction matters: A-B and B-A are two different connections.
  • Elements whose id Siren generates (subgraphs, namespaces, notes, blocks, etc.) use kind:number, numbered from 1 in source order (nested ones in the order they open).
Diagram Elements that can be targets Examples
Flowchart Nodes, edges, subgraphs B, A-B, A-B#2, e1 (an edge written A e1@--> B), subgraph:1
Class diagram Classes, relationships, namespaces, notes Animal, Animal-Dog, namespace:1, note:1
Sequence diagram Participants, messages, blocks, boxes, notes, activation bars Web, Web-Orders, loop:1, alt:1, box:1, note:1, activation:1
State diagram States, transitions, start/end points, concurrent regions Idle, Idle-Working, start:1, start:1-Idle, region:1
ER diagram Entities, relationships, subgraphs CUSTOMER, CUSTOMER:ORDER, subgraph:1
Gantt chart Tasks, vert markers, sections api, task1, section:1

ER diagram relationship ids are separated by a colon (CUSTOMER:ORDER), because entity names can themselves contain -.

These elements cannot be targets: a flowchart subgraph’s title (use subgraph:N), class members, state diagram notes (they move with the state they belong to), and ER diagram attributes.

A target must name exactly one drawn thing. In a flowchart, a node written A-B beside the edge A --> B both carry the id A-B, so an action on A-B is an error; give the edge an id of its own (A e1@--> B) or rename the node. A destroyed sequence participant’s closing box carries the participant’s id, so an action on the participant reaches it as well.

Rules

  • Elements never mentioned are visible from the start.
  • Each target gets at most one enter and one exit. For duplicates, the earliest step’s is kept; the rest are skipped with a warning. So an element cannot enter again after it exits.
  • Nothing else can happen to an element before it appears. For example, if an element does not enter until step 3, a highlight on it at step 2 is an error and that action is skipped. In the same step as the enter is fine.
  • Connections do not exit along with their endpoints. If an endpoint exits while its connection stays, Siren warns you; give the connection its own exit in the same step or earlier. Entering works the same way: nodes and edges each need their own enter.

Several timelines in one document

When one diagram has more than one story to tell, give each story its own named block instead of copying the diagram into a second file. A named block starts with timeline <name>: and runs to the next timeline header or the end of the file.

flowchart LR
  Cart --> Card --> Done
  Cart --> Wallet --> Done

timeline card:
  enter Card fade, enter Cart-Card fade
  enter Done fade, enter Card-Done fade

timeline wallet:
  enter Wallet fade, enter Cart-Wallet fade
  enter Done fade, enter Wallet-Done fade
  • A name is letters, digits, _ and -, and is case-sensitive. Each name can be declared once.
  • Either unnamed or named, never both. A document with named blocks cannot also hold the unnamed timeline:.
  • Each block is a timeline of its own. Its steps count from 1, and every rule above applies within that block alone, step 0 included: an element a block never mentions is visible from that block’s start, even if another block enters it later. So each block must enter everything it wants hidden at its start. In the example, card never mentions Wallet, so the wallet path is visible all through the card story.
  • Every block is checked on every render, whichever one is shown. A message about a named block starts with timeline <name>: instead of timeline:.
  • The first block plays by default. When a document names two or more timelines, the Playground, the Examples pages and siren-board show a dropdown of their names in the control bar; picking one plays that timeline from step 0. With siren-core, pass the name to render(source, container, { timeline: "wallet" }), and read the names from the result’s timelines.

The multi-timeline example walks one class diagram through two checkouts, by card and by wallet.

Error messages

Format errors keep the whole document from being drawn:

Message Cause
Unrecognized timeline action: "..." The action has the wrong number of words, has a trailing comma, or still uses the old step N: syntax
Unrecognized timeline verb "..." The verb is not enter, exit, highlight or unhighlight
Unknown enter effect "..." The effect is misspelled, or missing
"unhighlight" takes no effect unhighlight is followed by an effect
A document declares at most one unnamed "timeline:" block; name each block ("timeline <name>:") to declare several A second timeline:
An unnamed "timeline:" block cannot share a document with named ones; name every block, or declare only the unnamed one timeline: and timeline <name>: in the same document
Timeline "..." is already declared on line N Two blocks with the same name
Invalid timeline name "..." (a name is letters, digits, "_" and "-") The name holds other characters, such as a.b

Diagram syntax written after timeline: reports Unrecognized timeline verb or Unrecognized timeline action, depending on how the line is written.

Content errors skip only that action; the diagram is still drawn. In a named block, the message starts with timeline <name>: instead of timeline::

Message Cause
timeline: references unknown id "..." The target id does not exist. Common causes are using a subgraph’s title as its id, or writing an ER relationship as A-B
timeline: "..." already has a "enter" action The same target has two enters or two exits (warning)
timeline: "highlight" on "..." at step N comes before it becomes visible An action on an element before it appears
timeline: edge "..." remains visible after its endpoint "..." exits An endpoint exited but the connection is still there (warning)