diff --git a/docs/widgets/services/esphome.md b/docs/widgets/services/esphome.md
index 73f5c7edd..e14431fd8 100644
--- a/docs/widgets/services/esphome.md
+++ b/docs/widgets/services/esphome.md
@@ -7,7 +7,10 @@ Learn more about [ESPHome](https://esphome.io/).
 
 Show the number of ESPHome devices based on their state.
 
-Allowed fields: `["total", "online", "offline", "offline_alt", "unknown"]`.
+Allowed fields: `["total", "online", "offline", "offline_alt", "unknown"]` (maximum of 4).
+
+By default ESPHome will only mark devices as `offline` if their address cannot be pinged. If it has an invalid config or its name cannot be resolved (by DNS) its status will be marked as `unknown`.
+To group both `offline` and `unknown` devices together, users should use the `offline_alt` field instead. This sums all devices that are _not_ online together.
 
 ```yaml
 widget: