diff --git a/docs/core/entity/switch.md b/docs/core/entity/switch.md
index aeb7bfb4..36668e25 100644
--- a/docs/core/entity/switch.md
+++ b/docs/core/entity/switch.md
@@ -16,6 +16,13 @@ Properties should always only return information from memory and not do I/O (lik
 | Name | Type | Default | Description
 | ---- | ---- | ------- | -----------
 | is_on | boolean | **Required** | If the switch is currently on or off.
+
+## Deprecated Properties
+
+The following properties are deprecated and should not be used by new integrations. Provide them as sensors instead.
+
+Name | Type | Default | Description
+| ---- | ---- | ------- | -----------
 | current_power_w | float | `None` | The current power usage in W.
 | today_energy_kwh | float | `None` | Total energy usage in kWh.