From 6b64b92b6ef9eaf0b3f2504c20ca3e11f3fb093f Mon Sep 17 00:00:00 2001
From: omkarht <omkar@mermaidchart.com>
Date: Thu, 14 Aug 2025 12:58:24 +0530
Subject: [PATCH] docs: add documentation

on-behalf-of: @Mermaid-Chart <hello@mermaidchart.com>
---
 docs/syntax/sequenceDiagram.md                | 40 +++++++++++++++++++
 .../src/docs/syntax/sequenceDiagram.md        | 24 +++++++++++
 2 files changed, 64 insertions(+)

diff --git a/docs/syntax/sequenceDiagram.md b/docs/syntax/sequenceDiagram.md
index a8f502dcd..b45cc3f5a 100644
--- a/docs/syntax/sequenceDiagram.md
+++ b/docs/syntax/sequenceDiagram.md
@@ -194,6 +194,46 @@ sequenceDiagram
     Bob->>Alice: Queue response
 ```
 
+### Icon
+
+If you want to use a custom icon for a participant, use the JSON configuration syntax as shown below. The `icon` value can be a FontAwesome icon name, emoji, or other supported icon identifier.
+
+```mermaid-example
+sequenceDiagram
+    participant Alice@{ "type" : "icon", "icon": "fa:bell" }
+    participant Bob
+    Alice->>Bob: Icon participant
+    Bob->>Alice: Response to icon
+```
+
+```mermaid
+sequenceDiagram
+    participant Alice@{ "type" : "icon", "icon": "fa:bell" }
+    participant Bob
+    Alice->>Bob: Icon participant
+    Bob->>Alice: Response to icon
+```
+
+### Image
+
+If you want to use a custom image for a participant, use the JSON configuration syntax as shown below. The `image` value should be a valid image URL.
+
+```mermaid-example
+sequenceDiagram
+    participant Alice@{ "type" : "image", "image": "https://cdn.pixabay.com/photo/2020/02/22/18/49/paper-4871356_1280.jpg" }
+    participant Bob
+    Alice->>Bob: Image participant
+    Bob->>Alice: Response to image
+```
+
+```mermaid
+sequenceDiagram
+    participant Alice@{ "type" : "image", "image": "https://cdn.pixabay.com/photo/2020/02/22/18/49/paper-4871356_1280.jpg" }
+    participant Bob
+    Alice->>Bob: Image participant
+    Bob->>Alice: Response to image
+```
+
 ### Aliases
 
 The actor can have a convenient identifier and a descriptive label.
diff --git a/packages/mermaid/src/docs/syntax/sequenceDiagram.md b/packages/mermaid/src/docs/syntax/sequenceDiagram.md
index 6e0ac87bf..86b6b1937 100644
--- a/packages/mermaid/src/docs/syntax/sequenceDiagram.md
+++ b/packages/mermaid/src/docs/syntax/sequenceDiagram.md
@@ -118,6 +118,30 @@ sequenceDiagram
     Bob->>Alice: Queue response
 ```
 
+### Icon
+
+If you want to use a custom icon for a participant, use the JSON configuration syntax as shown below. The `icon` value can be a FontAwesome icon name, emoji, or other supported icon identifier.
+
+```mermaid-example
+sequenceDiagram
+    participant Alice@{ "type" : "icon", "icon": "fa:bell" }
+    participant Bob
+    Alice->>Bob: Icon participant
+    Bob->>Alice: Response to icon
+```
+
+### Image
+
+If you want to use a custom image for a participant, use the JSON configuration syntax as shown below. The `image` value should be a valid image URL.
+
+```mermaid-example
+sequenceDiagram
+    participant Alice@{ "type" : "image", "image": "https://cdn.pixabay.com/photo/2020/02/22/18/49/paper-4871356_1280.jpg" }
+    participant Bob
+    Alice->>Bob: Image participant
+    Bob->>Alice: Response to image
+```
+
 ### Aliases
 
 The actor can have a convenient identifier and a descriptive label.