> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/mermaid-js/mermaid/llms.txt
> Use this file to discover all available pages before exploring further.

# State diagrams

> Describe the behavior of systems using states and transitions

A state diagram describes the behavior of systems composed of a finite number of states. State diagrams show how one state can change to another state via a transition.

## Basic example

```mermaid theme={null}
---
title: Simple sample
---
stateDiagram-v2
    [*] --> Still
    Still --> [*]

    Still --> Moving
    Moving --> Still
    Moving --> Crash
    Crash --> [*]
```

<Note>
  Use `stateDiagram-v2` for the current renderer. The older `stateDiagram` syntax is also supported.
</Note>

## States

States can be declared in multiple ways:

### Simple state

```mermaid theme={null}
stateDiagram-v2
    stateId
```

### State with description

```mermaid theme={null}
stateDiagram-v2
    state "This is a state description" as s2
```

Or using colon notation:

```mermaid theme={null}
stateDiagram-v2
    s2 : This is a state description
```

## Transitions

Transitions are represented using `-->`:

```mermaid theme={null}
stateDiagram-v2
    s1 --> s2
```

### Transitions with text

```mermaid theme={null}
stateDiagram-v2
    s1 --> s2: A transition
```

## Start and end

Use `[*]` to indicate start and stop states:

```mermaid theme={null}
stateDiagram-v2
    [*] --> s1
    s1 --> [*]
```

## Composite states

States can contain internal states:

```mermaid theme={null}
stateDiagram-v2
    [*] --> First
    state First {
        [*] --> second
        second --> [*]
    }

    [*] --> NamedComposite
    NamedComposite: Another Composite
    state NamedComposite {
        [*] --> namedSimple
        namedSimple --> [*]
        namedSimple: Another simple
    }
```

### Nested composite states

```mermaid theme={null}
stateDiagram-v2
    [*] --> First

    state First {
        [*] --> Second

        state Second {
            [*] --> second
            second --> Third

            state Third {
                [*] --> third
                third --> [*]
            }
        }
    }
```

### Transitions between composite states

```mermaid theme={null}
stateDiagram-v2
    [*] --> First
    First --> Second
    First --> Third

    state First {
        [*] --> fir
        fir --> [*]
    }
    state Second {
        [*] --> sec
        sec --> [*]
    }
    state Third {
        [*] --> thi
        thi --> [*]
    }
```

## Choice

Model choices using `<<choice>>`:

```mermaid theme={null}
stateDiagram-v2
    state if_state <<choice>>
    [*] --> IsPositive
    IsPositive --> if_state
    if_state --> False: if n < 0
    if_state --> True : if n >= 0
```

## Forks

Specify forks and joins:

```mermaid theme={null}
stateDiagram-v2
 state fork_state <<fork>>
   [*] --> fork_state
   fork_state --> State2
   fork_state --> State3

   state join_state <<join>>
   State2 --> join_state
   State3 --> join_state
   join_state --> State4
   State4 --> [*]
```

## Notes

Add notes to states:

```mermaid theme={null}
stateDiagram-v2
    State1: The state with a note
    note right of State1
        Important information! You can write
        notes.
    end note
    State1 --> State2
    note left of State2 : This is the note to the left.
```

## Concurrency

Specify concurrency using `--`:

```mermaid theme={null}
stateDiagram-v2
    [*] --> Active

    state Active {
        [*] --> NumLockOff
        NumLockOff --> NumLockOn : EvNumLockPressed
        NumLockOn --> NumLockOff : EvNumLockPressed
        --
        [*] --> CapsLockOff
        CapsLockOff --> CapsLockOn : EvCapsLockPressed
        CapsLockOn --> CapsLockOff : EvCapsLockPressed
        --
        [*] --> ScrollLockOff
        ScrollLockOff --> ScrollLockOn : EvScrollLockPressed
        ScrollLockOn --> ScrollLockOff : EvScrollLockPressed
    }
```

## Direction

Set the rendering direction:

```mermaid theme={null}
stateDiagram
    direction LR
    [*] --> A
    A --> B
    B --> C
    state B {
      direction LR
      a --> b
    }
    B --> D
```

## Styling with classDefs

Apply custom styles to states:

```mermaid theme={null}
stateDiagram
   direction TB

   accTitle: This is the accessible title
   accDescr: This is an accessible description

   classDef notMoving fill:white
   classDef movement font-style:italic
   classDef badBadEvent fill:#f00,color:white,font-weight:bold,stroke-width:2px,stroke:yellow

   [*]--> Still
   Still --> [*]
   Still --> Moving
   Moving --> Still
   Moving --> Crash
   Crash --> [*]

   class Still notMoving
   class Moving, Crash movement
   class Crash badBadEvent
```

### Using the ::: operator

```mermaid theme={null}
stateDiagram
   direction TB

   classDef notMoving fill:white
   classDef movement font-style:italic;
   classDef badBadEvent fill:#f00,color:white,font-weight:bold,stroke-width:2px,stroke:yellow

   [*] --> Still:::notMoving
   Still --> [*]
   Still --> Moving:::movement
   Moving --> Still
   Moving --> Crash:::movement
   Crash:::badBadEvent --> [*]
```

<Accordion title="Styling limitations">
  1. Cannot be applied to start or end states
  2. Cannot be applied to or within composite states

  These limitations are being addressed in future versions.
</Accordion>

## Spaces in state names

Define states with IDs and reference them:

```mermaid theme={null}
stateDiagram
    classDef yourState font-style:italic,font-weight:bold,fill:white

    yswsii: Your state with spaces in it
    [*] --> yswsii:::yourState
    [*] --> SomeOtherState
    SomeOtherState --> YetAnotherState
    yswsii --> YetAnotherState
    YetAnotherState --> [*]
```

## Comments

Add comments with `%%`:

```mermaid theme={null}
stateDiagram-v2
    [*] --> Still
    Still --> [*]
%% this is a comment
    Still --> Moving
    Moving --> Still %% another comment
    Moving --> Crash
    Crash --> [*]
```