diff --git a/docs/configuration/examples.md b/docs/configuration/examples.md
index 010b039c17..17ab54f56e 100644
--- a/docs/configuration/examples.md
+++ b/docs/configuration/examples.md
@@ -287,6 +287,41 @@ newer and tmux 3.0 or newer.
 
 ````
 
+## `if` conditions
+
+tmuxp enables one to optionally open windows / panes based on coditions. The `if` conditions can appears in the configuration for window or pane.
+
+````{tab} YAML
+
+```{literalinclude} ../../examples/if-conditions.yaml
+:language: yaml
+
+```
+````
+
+````{tab} JSON
+
+```{literalinclude} ../../examples/if-conditions.json
+:language: json
+
+```
+
+````
+
+In the example, running the example
+
+```console
+$ tmuxp load examples/if-conditions.yaml
+```
+
+should produce **only** a window with upper and lower split panes (others should have `if` conditions that evaluates to false). This example allows for on-demand pane showing, where
+
+```console
+$ show_htop=false tmuxp load examples/if-conditions.yaml
+```
+
+will insteads suppress the `htop` command pane and resulting in a different behaviour.
+
 ## Focusing
 
 tmuxp allows `focus: true` for assuring windows and panes are attached /
diff --git a/examples/if-conditions.json b/examples/if-conditions.json
new file mode 100644
index 0000000000..1765326243
--- /dev/null
+++ b/examples/if-conditions.json
@@ -0,0 +1,49 @@
+{
+  "session_name": "if conditions test",
+  "environment": {
+    "Foo": "false",
+    "show_htop": "true"
+  },
+  "windows": [
+    {
+      "window_name": "window 1 ${ha} $Foo",
+      "if": {
+        "shell": "${Foo}"
+      },
+      "panes": [
+        {
+          "shell_command": [
+            "echo \"this shouldn't shows up\""
+          ]
+        },
+        "echo neither should this $Foo"
+      ]
+    },
+    {
+      "window_name": "window 2",
+      "panes": [
+        {
+          "if": {
+            "python": "1+1==3"
+          },
+          "shell_command": [
+            "echo the above is a false statement"
+          ]
+        },
+        {
+          "shell_command": [
+            "echo no condition",
+            "python -m http.server"
+          ]
+        },
+        {
+          "if": "${show_htop}",
+          "shell_command": [
+            "echo the above is a true statement (by default), but can be disabled on-demand",
+            "htop"
+          ]
+        }
+      ]
+    }
+  ]
+}
\ No newline at end of file
diff --git a/examples/if-conditions.yaml b/examples/if-conditions.yaml
new file mode 100644
index 0000000000..425aec4325
--- /dev/null
+++ b/examples/if-conditions.yaml
@@ -0,0 +1,29 @@
+session_name: if conditions test
+environment:
+  Foo: 'false'
+  show_htop: 'true'
+windows:
+  # the following would not shows up as it evaluates to false
+  - window_name: window 1 ${ha} $Foo
+    if:
+      shell: ${Foo}
+    panes:
+      - shell_command:
+          - echo "this shouldn't shows up"
+      - echo neither should this $Foo
+  - window_name: window 2
+    panes:
+      # should not shows up
+      - if:
+          python: 1+1==3
+        shell_command:
+          - echo the above is a false statement
+      # no if conditions
+      - shell_command:
+          - echo no condition
+          - python -m http.server
+      # display by default, but can be disabled by running `show_htop=false tmuxp load .....`
+      - if: ${show_htop}
+        shell_command:
+          - echo the above is a true statement (by default), but can be disabled on-demand
+          - htop