15.9 KB673 lines
Blame
1> **Warning**
2>
3> ## THIS IS AN AUTOGENERATED FILE. DO NOT EDIT.
4>
5> ## Please edit the corresponding file in [/packages/mermaid/src/docs/syntax/stateDiagram.md](../../packages/mermaid/src/docs/syntax/stateDiagram.md).
6
7# State diagrams
8
9> "A state diagram is a type of diagram used in computer science and related fields to describe the behavior of systems.
10> State diagrams require that the system described is composed of a finite number of states; sometimes, this is indeed the
11> case, while at other times this is a reasonable abstraction." Wikipedia
12
13Mermaid can render state diagrams. The syntax tries to be compliant with the syntax used in plantUml as this will make
14it easier for users to share diagrams between mermaid and plantUml.
15
16```mermaid-example
17---
18title: Simple sample
19---
20stateDiagram-v2
21 [*] --> Still
22 Still --> [*]
23
24 Still --> Moving
25 Moving --> Still
26 Moving --> Crash
27 Crash --> [*]
28```
29
30```mermaid
31---
32title: Simple sample
33---
34stateDiagram-v2
35 [*] --> Still
36 Still --> [*]
37
38 Still --> Moving
39 Moving --> Still
40 Moving --> Crash
41 Crash --> [*]
42```
43
44Older renderer:
45
46```mermaid-example
47stateDiagram
48 [*] --> Still
49 Still --> [*]
50
51 Still --> Moving
52 Moving --> Still
53 Moving --> Crash
54 Crash --> [*]
55```
56
57```mermaid
58stateDiagram
59 [*] --> Still
60 Still --> [*]
61
62 Still --> Moving
63 Moving --> Still
64 Moving --> Crash
65 Crash --> [*]
66```
67
68In state diagrams systems are described in terms of _states_ and how one _state_ can change to another _state_ via
69a _transition._ The example diagram above shows three states: **Still**, **Moving** and **Crash**. You start in the
70**Still** state. From **Still** you can change to the **Moving** state. From **Moving** you can change either back to the **Still** state or to
71the **Crash** state. There is no transition from **Still** to **Crash**. (You can't crash if you're still.)
72
73## States
74
75A state can be declared in multiple ways. The simplest way is to define a state with just an id:
76
77```mermaid-example
78stateDiagram-v2
79 stateId
80```
81
82```mermaid
83stateDiagram-v2
84 stateId
85```
86
87Another way is by using the state keyword with a description as per below:
88
89```mermaid-example
90stateDiagram-v2
91 state "This is a state description" as s2
92```
93
94```mermaid
95stateDiagram-v2
96 state "This is a state description" as s2
97```
98
99Another way to define a state with a description is to define the state id followed by a colon and the description:
100
101```mermaid-example
102stateDiagram-v2
103 s2 : This is a state description
104```
105
106```mermaid
107stateDiagram-v2
108 s2 : This is a state description
109```
110
111## Transitions
112
113Transitions are path/edges when one state passes into another. This is represented using text arrow, "-->".
114
115When you define a transition between two states and the states are not already defined, the undefined states are defined
116with the id from the transition. You can later add descriptions to states defined this way.
117
118```mermaid-example
119stateDiagram-v2
120 s1 --> s2
121```
122
123```mermaid
124stateDiagram-v2
125 s1 --> s2
126```
127
128It is possible to add text to a transition to describe what it represents:
129
130```mermaid-example
131stateDiagram-v2
132 s1 --> s2: A transition
133```
134
135```mermaid
136stateDiagram-v2
137 s1 --> s2: A transition
138```
139
140## Start and End
141
142There are two special states indicating the start and stop of the diagram. These are written with the \[\*] syntax and
143the direction of the transition to it defines it either as a start or a stop state.
144
145```mermaid-example
146stateDiagram-v2
147 [*] --> s1
148 s1 --> [*]
149```
150
151```mermaid
152stateDiagram-v2
153 [*] --> s1
154 s1 --> [*]
155```
156
157## Composite states
158
159In a real world use of state diagrams you often end up with diagrams that are multidimensional as one state can
160have several internal states. These are called composite states in this terminology.
161
162In order to define a composite state you need to use the state keyword followed by an id and the body of the composite
163state between {}. You can name a composite state on a separate line just like a simple state. See the example below:
164
165```mermaid-example
166stateDiagram-v2
167 [*] --> First
168 state First {
169 [*] --> second
170 second --> [*]
171 }
172
173 [*] --> NamedComposite
174 NamedComposite: Another Composite
175 state NamedComposite {
176 [*] --> namedSimple
177 namedSimple --> [*]
178 namedSimple: Another simple
179 }
180```
181
182```mermaid
183stateDiagram-v2
184 [*] --> First
185 state First {
186 [*] --> second
187 second --> [*]
188 }
189
190 [*] --> NamedComposite
191 NamedComposite: Another Composite
192 state NamedComposite {
193 [*] --> namedSimple
194 namedSimple --> [*]
195 namedSimple: Another simple
196 }
197```
198
199You can do this in several layers:
200
201```mermaid-example
202stateDiagram-v2
203 [*] --> First
204
205 state First {
206 [*] --> Second
207
208 state Second {
209 [*] --> second
210 second --> Third
211
212 state Third {
213 [*] --> third
214 third --> [*]
215 }
216 }
217 }
218```
219
220```mermaid
221stateDiagram-v2
222 [*] --> First
223
224 state First {
225 [*] --> Second
226
227 state Second {
228 [*] --> second
229 second --> Third
230
231 state Third {
232 [*] --> third
233 third --> [*]
234 }
235 }
236 }
237```
238
239You can also define transitions also between composite states:
240
241```mermaid-example
242stateDiagram-v2
243 [*] --> First
244 First --> Second
245 First --> Third
246
247 state First {
248 [*] --> fir
249 fir --> [*]
250 }
251 state Second {
252 [*] --> sec
253 sec --> [*]
254 }
255 state Third {
256 [*] --> thi
257 thi --> [*]
258 }
259```
260
261```mermaid
262stateDiagram-v2
263 [*] --> First
264 First --> Second
265 First --> Third
266
267 state First {
268 [*] --> fir
269 fir --> [*]
270 }
271 state Second {
272 [*] --> sec
273 sec --> [*]
274 }
275 state Third {
276 [*] --> thi
277 thi --> [*]
278 }
279```
280
281_You cannot define transitions between internal states belonging to different composite states_
282
283## Choice
284
285Sometimes you need to model a choice between two or more paths, you can do so using <\<choice>>.
286
287```mermaid-example
288stateDiagram-v2
289 state if_state <<choice>>
290 [*] --> IsPositive
291 IsPositive --> if_state
292 if_state --> False: if n < 0
293 if_state --> True : if n >= 0
294```
295
296```mermaid
297stateDiagram-v2
298 state if_state <<choice>>
299 [*] --> IsPositive
300 IsPositive --> if_state
301 if_state --> False: if n < 0
302 if_state --> True : if n >= 0
303```
304
305## Forks
306
307It is possible to specify a fork in the diagram using <\<fork>> <\<join>>.
308
309```mermaid-example
310 stateDiagram-v2
311 state fork_state <<fork>>
312 [*] --> fork_state
313 fork_state --> State2
314 fork_state --> State3
315
316 state join_state <<join>>
317 State2 --> join_state
318 State3 --> join_state
319 join_state --> State4
320 State4 --> [*]
321```
322
323```mermaid
324 stateDiagram-v2
325 state fork_state <<fork>>
326 [*] --> fork_state
327 fork_state --> State2
328 fork_state --> State3
329
330 state join_state <<join>>
331 State2 --> join_state
332 State3 --> join_state
333 join_state --> State4
334 State4 --> [*]
335```
336
337## Notes
338
339Sometimes nothing says it better than a Post-it note. That is also the case in state diagrams.
340
341Here you can choose to put the note to the _right of_ or to the _left of_ a node.
342
343```mermaid-example
344 stateDiagram-v2
345 State1: The state with a note
346 note right of State1
347 Important information! You can write
348 notes.
349 end note
350 State1 --> State2
351 note left of State2 : This is the note to the left.
352```
353
354```mermaid
355 stateDiagram-v2
356 State1: The state with a note
357 note right of State1
358 Important information! You can write
359 notes.
360 end note
361 State1 --> State2
362 note left of State2 : This is the note to the left.
363```
364
365## Concurrency
366
367As in plantUml you can specify concurrency using the -- symbol.
368
369```mermaid-example
370stateDiagram-v2
371 [*] --> Active
372
373 state Active {
374 [*] --> NumLockOff
375 NumLockOff --> NumLockOn : EvNumLockPressed
376 NumLockOn --> NumLockOff : EvNumLockPressed
377 --
378 [*] --> CapsLockOff
379 CapsLockOff --> CapsLockOn : EvCapsLockPressed
380 CapsLockOn --> CapsLockOff : EvCapsLockPressed
381 --
382 [*] --> ScrollLockOff
383 ScrollLockOff --> ScrollLockOn : EvScrollLockPressed
384 ScrollLockOn --> ScrollLockOff : EvScrollLockPressed
385 }
386```
387
388```mermaid
389stateDiagram-v2
390 [*] --> Active
391
392 state Active {
393 [*] --> NumLockOff
394 NumLockOff --> NumLockOn : EvNumLockPressed
395 NumLockOn --> NumLockOff : EvNumLockPressed
396 --
397 [*] --> CapsLockOff
398 CapsLockOff --> CapsLockOn : EvCapsLockPressed
399 CapsLockOn --> CapsLockOff : EvCapsLockPressed
400 --
401 [*] --> ScrollLockOff
402 ScrollLockOff --> ScrollLockOn : EvScrollLockPressed
403 ScrollLockOn --> ScrollLockOff : EvScrollLockPressed
404 }
405```
406
407## Setting the direction of the diagram
408
409With state diagrams you can use the direction statement to set the direction which the diagram will render like in this
410example.
411
412```mermaid-example
413stateDiagram
414 direction LR
415 [*] --> A
416 A --> B
417 B --> C
418 state B {
419 direction LR
420 a --> b
421 }
422 B --> D
423```
424
425```mermaid
426stateDiagram
427 direction LR
428 [*] --> A
429 A --> B
430 B --> C
431 state B {
432 direction LR
433 a --> b
434 }
435 B --> D
436```
437
438## Comments
439
440Comments can be entered within a state diagram chart, which will be ignored by the parser. Comments need to be on their
441own line, and must be prefaced with `%%` (double percent signs). Any text after the start of the comment to the next
442newline will be treated as a comment, including any diagram syntax
443
444```mermaid-example
445stateDiagram-v2
446 [*] --> Still
447 Still --> [*]
448%% this is a comment
449 Still --> Moving
450 Moving --> Still %% another comment
451 Moving --> Crash
452 Crash --> [*]
453```
454
455```mermaid
456stateDiagram-v2
457 [*] --> Still
458 Still --> [*]
459%% this is a comment
460 Still --> Moving
461 Moving --> Still %% another comment
462 Moving --> Crash
463 Crash --> [*]
464```
465
466## Styling with classDefs
467
468As with other diagrams (like flowcharts), you can define a style in the diagram itself and apply that named style to a
469state or states in the diagram.
470
471**These are the current limitations with state diagram classDefs:**
472
4731. Cannot be applied to start or end states
4742. Cannot be applied to or within composite states
475
476_These are in development and will be available in a future version._
477
478You define a style using the `classDef` keyword, which is short for "class definition" (where "class" means something
479like a _CSS class_)
480followed by _a name for the style,_
481and then one or more _property-value pairs_. Each _property-value pair_ is
482a _[valid CSS property name](https://www.w3.org/TR/CSS/#properties)_ followed by a colon (`:`) and then a _value._
483
484Here is an example of a classDef with just one property-value pair:
485
486```txt
487classDef movement font-style:italic;
488```
489
490where
491
492- the _name_ of the style is `movement`
493- the only _property_ is `font-style` and its _value_ is `italic`
494
495If you want to have more than one _property-value pair_ then you put a comma (`,`) between each _property-value pair._
496
497Here is an example with three property-value pairs:
498
499```txt
500classDef badBadEvent fill:#f00,color:white,font-weight:bold,stroke-width:2px,stroke:yellow
501```
502
503where
504
505- the _name_ of the style is `badBadEvent`
506- the first _property_ is `fill` and its _value_ is `#f00`
507- the second _property_ is `color` and its _value_ is `white`
508- the third _property_ is `font-weight` and its _value_ is `bold`
509- the fourth _property_ is `stroke-width` and its _value_ is `2px`
510- the fifth _property_ is `stroke` and its _value_ is `yellow`
511
512### Apply classDef styles to states
513
514There are two ways to apply a `classDef` style to a state:
515
5161. use the `class` keyword to apply a classDef style to one or more states in a single statement, or
5172. use the `:::` operator to apply a classDef style to a state as it is being used in a transition statement (e.g. with an arrow
518 to/from another state)
519
520#### 1. `class` statement
521
522A `class` statement tells Mermaid to apply the named classDef to one or more classes. The form is:
523
524```txt
525class [one or more state names, separated by commas] [name of a style defined with classDef]
526```
527
528Here is an example applying the `badBadEvent` style to a state named `Crash`:
529
530```txt
531class Crash badBadEvent
532```
533
534Here is an example applying the `movement` style to the two states `Moving` and `Crash`:
535
536```txt
537class Moving, Crash movement
538```
539
540Here is a diagram that shows the examples in use. Note that the `Crash` state has two classDef styles applied: `movement`
541and `badBadEvent`
542
543```mermaid-example
544 stateDiagram
545 direction TB
546
547 accTitle: This is the accessible title
548 accDescr: This is an accessible description
549
550 classDef notMoving fill:white
551 classDef movement font-style:italic
552 classDef badBadEvent fill:#f00,color:white,font-weight:bold,stroke-width:2px,stroke:yellow
553
554 [*]--> Still
555 Still --> [*]
556 Still --> Moving
557 Moving --> Still
558 Moving --> Crash
559 Crash --> [*]
560
561 class Still notMoving
562 class Moving, Crash movement
563 class Crash badBadEvent
564 class end badBadEvent
565```
566
567```mermaid
568 stateDiagram
569 direction TB
570
571 accTitle: This is the accessible title
572 accDescr: This is an accessible description
573
574 classDef notMoving fill:white
575 classDef movement font-style:italic
576 classDef badBadEvent fill:#f00,color:white,font-weight:bold,stroke-width:2px,stroke:yellow
577
578 [*]--> Still
579 Still --> [*]
580 Still --> Moving
581 Moving --> Still
582 Moving --> Crash
583 Crash --> [*]
584
585 class Still notMoving
586 class Moving, Crash movement
587 class Crash badBadEvent
588 class end badBadEvent
589```
590
591#### 2. `:::` operator to apply a style to a state
592
593You can apply a classDef style to a state using the `:::` (three colons) operator. The syntax is
594
595```txt
596[state]:::[style name]
597```
598
599You can use this in a diagram within a statement using a class. This includes the start and end states. For example:
600
601```mermaid-example
602stateDiagram
603 direction TB
604
605 accTitle: This is the accessible title
606 accDescr: This is an accessible description
607
608 classDef notMoving fill:white
609 classDef movement font-style:italic;
610 classDef badBadEvent fill:#f00,color:white,font-weight:bold,stroke-width:2px,stroke:yellow
611
612 [*] --> Still:::notMoving
613 Still --> [*]
614 Still --> Moving:::movement
615 Moving --> Still
616 Moving --> Crash:::movement
617 Crash:::badBadEvent --> [*]
618```
619
620```mermaid
621stateDiagram
622 direction TB
623
624 accTitle: This is the accessible title
625 accDescr: This is an accessible description
626
627 classDef notMoving fill:white
628 classDef movement font-style:italic;
629 classDef badBadEvent fill:#f00,color:white,font-weight:bold,stroke-width:2px,stroke:yellow
630
631 [*] --> Still:::notMoving
632 Still --> [*]
633 Still --> Moving:::movement
634 Moving --> Still
635 Moving --> Crash:::movement
636 Crash:::badBadEvent --> [*]
637```
638
639## Spaces in state names
640
641Spaces can be added to a state by first defining the state with an id and then referencing the id later.
642
643In the following example there is a state with the id **yswsii** and description **Your state with spaces in it**.
644After it has been defined, **yswsii** is used in the diagram in the first transition (`[*] --> yswsii`)
645and also in the transition to **YetAnotherState** (`yswsii --> YetAnotherState`).
646(**yswsii** has been styled so that it is different from the other states.)
647
648```mermaid-example
649stateDiagram
650 classDef yourState font-style:italic,font-weight:bold,fill:white
651
652 yswsii: Your state with spaces in it
653 [*] --> yswsii:::yourState
654 [*] --> SomeOtherState
655 SomeOtherState --> YetAnotherState
656 yswsii --> YetAnotherState
657 YetAnotherState --> [*]
658```
659
660```mermaid
661stateDiagram
662 classDef yourState font-style:italic,font-weight:bold,fill:white
663
664 yswsii: Your state with spaces in it
665 [*] --> yswsii:::yourState
666 [*] --> SomeOtherState
667 SomeOtherState --> YetAnotherState
668 yswsii --> YetAnotherState
669 YetAnotherState --> [*]
670```
671
672<!--- cspell:ignore yswsii --->
673