ESPHome devices have long been able to mirror a Home Assistant switch and flip it from a button or a display. For lights that meant on and off only, unless you wrote your own homeassistant.action calls. A new homeassistant light platform fills the gap: it creates a light on the device that follows a light entity in Home Assistant and controls it over the native API, brightness, colour temperature and colour included. GitHub user egormanga opened the pull request on 19 October 2025, and J. Nick Koston (bdraco) merged it into the development branch on 18 October 2026 at 22:02 Polish time, almost exactly a year later. It resolves a feature request from May 2025 and is aimed at ESPHome 2026.11. The documentation pull request is still open.

What it looks like

light:
  - platform: homeassistant
    id: living_room
    entity_id: light.living_room

button:
  - platform: template
    name: "Living room dim"
    on_press:
      - light.turn_on:
          id: living_room
          brightness: 40%
          color_temperature: 370 mireds

On the device it behaves like any other light. You can use it in automations, with the usual light actions, on a display or through LVGL. That is handy for wall panels and knobs that should drive a Zigbee or Matter lamp already set up in Home Assistant.

How the two sides stay in sync

The state, colour mode, brightness, colour temperature and colour follow the Home Assistant entity. The supported colour modes and the colour temperature range come from Home Assistant as well, so color_temperature is given in mireds within that range. Home Assistant has worked only in kelvin since it dropped the mired attributes in 2026.3, so the platform converts in both directions.

A change made on the device goes out as light.turn_on or light.turn_off. The colour temperature or colour is sent only when it, or the colour mode, has changed. A colour is sent as rgb_color, which Home Assistant converts to the lamp's own channels, and a brightness-only change keeps the white balance of a warm/cold white lamp. Effects run on the device and drive the real lamp through the same actions. A transition runs on the device alone, and Home Assistant only receives the state it ends in. A flash is never sent, and the log says so.

After each change, the device waits for Home Assistant to report the new state. If no report arrives within report_timeout, 10 seconds by default and up to 255 seconds, ESPHome logs a warning and puts the light back to the state reported last. That covers cases such as no Home Assistant connection yet, an unavailable entity or a refused action. For lights that Home Assistant only polls, the docs suggest a longer timeout, since a report can take a minute.

Nothing is saved or restored on the device, because the state always comes from Home Assistant. Gamma correction and the default transition are off, since Home Assistant renders the light.

Before you try it

As with the other homeassistant platforms, the device has to be added to Home Assistant, even if you do not want any of its entities there. The light sends its changes as Home Assistant actions. The ESPHome integration in Home Assistant does not allow newly added devices to perform actions by default, so you turn on Allow the device to perform Home Assistant actions in that device's options.