From 8a1501d282e6115feb2f96dedf80f031ed51dee2 Mon Sep 17 00:00:00 2001
From: Elson Correia <design@elsoncorreia.com>
Date: Sat, 19 Oct 2024 09:57:47 -0400
Subject: [PATCH] the when doc

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

diff --git a/docs/documentation/utilities/when.md b/docs/documentation/utilities/when.md
index b99f31aa..63107cd0 100644
--- a/docs/documentation/utilities/when.md
+++ b/docs/documentation/utilities/when.md
@@ -7,3 +7,35 @@ layout: document
 ---
 
 ## When Utility
+
+The `when` helper is Markup out of the box utility to do conditional rendering in or outside templates.
+
+It mimics an if-and-else statement with the else being conditional.
+
+```javascript
+const visible = true
+
+html` <p>${when(visible, `visible`, `hidden`)}</p> `
+```
+
+### Condition
+
+The condition is the first argument and it can be a static value or a function for something that will change like a [StateGetter](../state/index.md#stategetter).
+
+```javascript
+const [visible, updateVisible] = state(true)
+
+html` ${when(visible, html`<p>visible</p>`, html`<p>hidden</p>`)} `
+```
+
+The `when` helper will re-evaluate whenever the condition changes for an accurate render.
+
+### Then & else
+
+The second argument is required and represent the "then" value while the third argument is optional since it represent the "else" body.
+
+```javascript
+const [visible, updateVisible] = state(true)
+
+html`${when(visible, html`<p>visible</p>`)}`
+```