From d530f6459811560edd1a5cf192bb15c2c399291b Mon Sep 17 00:00:00 2001
From: Elson Correia <design@elsoncorreia.com>
Date: Fri, 18 Oct 2024 15:29:14 -0400
Subject: [PATCH] suspense doc

---
 docs/documentation/utilities/suspense.md | 44 ++++++++++++++++++++++++
 1 file changed, 44 insertions(+)

diff --git a/docs/documentation/utilities/suspense.md b/docs/documentation/utilities/suspense.md
index 56dfb1be..23bc3e76 100644
--- a/docs/documentation/utilities/suspense.md
+++ b/docs/documentation/utilities/suspense.md
@@ -7,3 +7,47 @@ layout: document
 ---
 
 ## Suspense Utility
+
+The `suspense` utility allows you to lazy render content by using the [replace](../templating/index.md#replace) method in the template instances while allowing you to handle the loading and error state.
+
+```javascript
+const loadTodos = async () => {
+    const res = await fetch('/api/todos')
+
+    if (!res.ok) {
+        throw new Error(`${res.status}: ${res.statusText}`)
+    }
+
+    const { result } = await res.json()
+
+    return result.map((item) => html`<li>${item.name}</li>`)
+}
+
+html`<ul>
+    ${suspense(loadTodos)}
+</ul>`.render(document.body)
+```
+
+### Loading state
+
+You can pass a custom loading content to render while the asynchronous work is being performed. The `suspense` has a default loading indicator that might not be what you want.
+
+```javascript
+html`<ul>
+    ${suspense(loadTodos, html`<loading-spinner></loading-spinner>`)}
+</ul>`.render(document.body)
+```
+
+### Error state
+
+You can also provide a function as third argument to handle how you want to display any errors. The `suspense` has a default way that might not be what you want.
+
+```javascript
+html`<ul>
+    ${suspense(
+        loadTodos,
+        html`<loading-spinner></loading-spinner>`,
+        (error) => html`<error-display error="${error}"></error-display>`
+    )}
+</ul>`.render(document.body)
+```