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:, ortimeline <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 withtimelineis 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 noalland 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 --> %%Bdraws a node%%B): a%%glued to the start of the target is the id’s, soenter %%B fadereaches 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 Nin 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. Writingstep 1:now reportsUnrecognized timeline action; just delete thestep 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, writeA-B#2,A-B#3, numbered in order of appearance. Direction matters:A-BandB-Aare 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
enterand oneexit. 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
enteruntil step 3, ahighlighton it at step 2 is an error and that action is skipped. In the same step as theenteris 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
exitin the same step or earlier. Entering works the same way: nodes and edges each need their ownenter.
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
entereverything it wants hidden at its start. In the example,cardnever mentionsWallet, 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 oftimeline:. - The first block plays by default. When a document names two or more timelines, the Playground, the Examples pages and
siren-boardshow a dropdown of their names in the control bar; picking one plays that timeline from step 0. Withsiren-core, pass the name torender(source, container, { timeline: "wallet" }), and read the names from the result’stimelines.
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) |