diff --git a/docs/reference/gtk/images/meson.build b/docs/reference/gtk/images/meson.build
index d3bff0ce3f..9260583bf0 100644
--- a/docs/reference/gtk/images/meson.build
+++ b/docs/reference/gtk/images/meson.build
@@ -68,6 +68,7 @@ ui_files = [
   'stackswitcher.ui',
   'statusbar.ui',
   'switch.ui',
+  'switch-state.ui',
   'toggle-button.ui',
   'video.ui',
   'volumebutton.ui',
diff --git a/docs/reference/gtk/images/switch-state.png b/docs/reference/gtk/images/switch-state.png
new file mode 100644
index 0000000000..97a965b4ef
Binary files /dev/null and b/docs/reference/gtk/images/switch-state.png differ
diff --git a/docs/reference/gtk/images/switch-state.ui b/docs/reference/gtk/images/switch-state.ui
new file mode 100644
index 0000000000..e087058e87
--- /dev/null
+++ b/docs/reference/gtk/images/switch-state.ui
@@ -0,0 +1,43 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<interface>
+  <object class="GtkWindow">
+    <property name="decorated">0</property>
+    <property name="resizable">0</property>
+    <property name="default-width">280</property>
+    <property name="default-height">120</property>
+    <style>
+       <class name="nobackground"/>
+    </style>
+    <child>
+      <object class="GtkBox">
+        <style>
+          <class name="shadow"/>
+          <class name="background"/>
+          <class name="frame"/>
+        </style>
+        <child>
+          <object class="GtkBox">
+            <property name="orientation">vertical</property>
+            <property name="spacing">3</property>
+            <property name="hexpand">1</property>
+            <property name="vexpand">1</property>
+            <property name="halign">center</property>
+            <property name="valign">center</property>
+            <child>
+              <object class="GtkSwitch">
+                <property name="active">1</property>
+                <property name="state">0</property>
+              </object>
+            </child>
+            <child>
+              <object class="GtkSwitch">
+                <property name="active">0</property>
+                <property name="state">1</property>
+              </object>
+            </child>
+          </object>
+        </child>
+      </object>
+    </child>
+  </object>
+</interface>
diff --git a/gtk/gtkswitch.c b/gtk/gtkswitch.c
index 31d2d234f5..7193d8b7c5 100644
--- a/gtk/gtkswitch.c
+++ b/gtk/gtkswitch.c
@@ -34,7 +34,14 @@
  * empty area, or by dragging the handle.
  *
  * `GtkSwitch` can also handle situations where the underlying state
- * changes with a delay. See [signal@Gtk.Switch::state-set] for details.
+ * changes with a delay. In this case, the slider position indicates
+ * the user's recent change (as indicated by the [property@Gtk.Switch:active]
+ * property), and the color indicates whether the underlying state (represented
+ * by the [property@Gtk.Switch:state] property) has been updated yet.
+ *
+ * ![GtkSwitch with delayed state change](switch-state.png)
+ *
+ * See [signal@Gtk.Switch::state-set] for details.
  *
  * # CSS nodes
  *