diff --git a/docs/syntax/stateDiagram.md b/docs/syntax/stateDiagram.md
index 7c40a5d2fb..a6b06a4b73 100644
--- a/docs/syntax/stateDiagram.md
+++ b/docs/syntax/stateDiagram.md
@@ -160,7 +160,7 @@ In a real world use of state diagrams you often end up with diagrams that are mu
 have several internal states. These are called composite states in this terminology.
 
 In order to define a composite state you need to use the state keyword followed by an id and the body of the composite
-state between {}. See the example below:
+state between {}. You can name a composite state on a separate line just like a simple state. See the example below:
 
 ```mermaid-example
 stateDiagram-v2
@@ -169,6 +169,14 @@ stateDiagram-v2
         [*] --> second
         second --> [*]
     }
+
+    [*] --> NamedComposite
+    NamedComposite: Another Composite
+    state NamedComposite {
+        [*] --> namedSimple
+        namedSimple --> [*]
+        namedSimple: Another simple
+    }
 ```
 
 ```mermaid
@@ -178,6 +186,14 @@ stateDiagram-v2
         [*] --> second
         second --> [*]
     }
+
+    [*] --> NamedComposite
+    NamedComposite: Another Composite
+    state NamedComposite {
+        [*] --> namedSimple
+        namedSimple --> [*]
+        namedSimple: Another simple
+    }
 ```
 
 You can do this in several layers:
diff --git a/packages/mermaid/src/docs/syntax/stateDiagram.md b/packages/mermaid/src/docs/syntax/stateDiagram.md
index d2b7282e4a..a287d41682 100644
--- a/packages/mermaid/src/docs/syntax/stateDiagram.md
+++ b/packages/mermaid/src/docs/syntax/stateDiagram.md
@@ -98,7 +98,7 @@ In a real world use of state diagrams you often end up with diagrams that are mu
 have several internal states. These are called composite states in this terminology.
 
 In order to define a composite state you need to use the state keyword followed by an id and the body of the composite
-state between \{\}. See the example below:
+state between \{\}. You can name a composite state on a separate line just like a simple state. See the example below:
 
 ```mermaid-example
 stateDiagram-v2
@@ -107,6 +107,14 @@ stateDiagram-v2
         [*] --> second
         second --> [*]
     }
+
+    [*] --> NamedComposite
+    NamedComposite: Another Composite
+    state NamedComposite {
+        [*] --> namedSimple
+        namedSimple --> [*]
+        namedSimple: Another simple
+    }
 ```
 
 You can do this in several layers: