The condition and script APIs have been changed.

Conditions are now instances of condition classes, which are evaluated by calling the async_check method and discarded by calling the async_unload method. Also, conditions may optionally implement an _async_setup or _async_unload method. Note that users of conditions don't need to call the condition's async_setup method.

During a deprecation period, which ends with the release of Home Assistant Core 2027.1, it's possible to use the condition object as a callable.

Scripts also have an async_unload method which must be called when the script is no longer needed.

Impact on custom integrations​

Custom integrations which create conditions or scripts​

Custom integrations which create condition objects should evaluate them by calling the async_check method and call the async_unload method when the condition is no longer needed.

Example:

from homeassistant.helpers.condition import (
    async_condition_from_config,
    async_validate_condition_config,
)

# Validate condition config
validated_config = await async_validate_condition_config(hass, config)

# Create a condition
condition = await async_condition_from_config(hass, validated_config)

...

# Evaluate the condition
result = condition.async_check(...)
...

# Discard the condition
condition.async_unload()

Custom integrations which create scripts should call the async_unload method when the script is no longer needed.

Example:

from homeassistant.helpers.script import (
    Script,
    async_validate_actions_config,
)

# Validate script config
validated_config = await async_validate_actions_config(hass, config)

# Create a script
script = Script(hass, validated_config, ...)

...

# Execute the script
result = await script.async_run(...)
...

# Discard the script
await script.async_unload()

Custom integrations which provide a condition platform​

Integrations which provide a condition platform don't need to change, but may implement _async_setup and _async_unload method if the platform needs to perform async initialization or do tear down.

Example:

from homeassistant.core import HomeAssistant
from homeassistant.helpers.condition import (
    Condition,
    ConditionCheckParams,
    ConditionConfig,
)
from homeassistant.helpers.typing import ConfigType

class CustomCondition(Condition):
    """A custom condition."""

    @classmethod
    async def async_validate_config(
        cls, hass: HomeAssistant, config: ConfigType
    ) -> ConfigType:
        """Validate config."""
        ...

    def __init__(self, hass: HomeAssistant, config: ConditionConfig) -> None:
        """Initialize condition."""
        super().__init__(hass, config)
        ...

    async def _async_setup(self) -> None:
        """Set up the condition checker."""
        ...

    def _async_unload(self) -> None:
        """Clean up any resources held by the checker."""
        ...

    def _async_check(self, **kwargs: Unpack[ConditionCheckParams]) -> bool:
        """Check the condition."""
        ...

Given a temperature sensor named Temperature on a device named Thermostat:

const stateObj = hass.states["sensor.living_room_thermostat_temperature"];

hass.formatEntityName(
  stateObj,
  [{ type: "device" }, { type: "entity" }],
  { separator: " · " }
); // "Thermostat · Temperature"

The frontend also ships an entity_name selector. If your card uses the built-in form editor, you can offer users the same name picker the built-in cards use — accepting either a free-form string or a composition of registry items.

Take a look at the updated data documentation for the full reference and more examples.

The new API signatures are:

def publish(
    hass: HomeAssistant,
    topic: str,
    payload: PublishPayloadType,
    qos: int = 0,
    retain: bool = False,
    encoding: str | None = DEFAULT_ENCODING,
) -> None:
    """Publish message to a MQTT topic."""
    hass.create_task(async_publish(hass, topic, payload, qos, retain, encoding))

and

async def async_publish(
    hass: HomeAssistant,
    topic: str,
    payload: PublishPayloadType,
    qos: int = 0,
    retain: bool = False,
    encoding: str | None = DEFAULT_ENCODING,
) -> None:
    """Publish message to a MQTT topic."""

The new API signatures are:

def publish(
    hass: HomeAssistant,
    topic: str,
    payload: PublishPayloadType,
    qos: int = 0,
    retain: bool = False,
    encoding: str | None = DEFAULT_ENCODING,
    *,
    message_expiry_interval: int | None = None,
) -> None:
    """Publish message to a MQTT topic."""

and

async def async_publish(
    hass: HomeAssistant,
    topic: str,
    payload: PublishPayloadType,
    qos: int = 0,
    retain: bool = False,
    encoding: str | None = DEFAULT_ENCODING,
    *,
    message_expiry_interval: int | None = None,
) -> None:
    """Publish message to a MQTT topic."""

Background​

Using a config entry listener together with any reloading methods in a config flow can cause the integration to reload twice and/or create a race condition.

Possible solutions​

• Remove the config entry listener and rely only on the reloading methods in your config flow.
• Use async_update_and_abort() instead of async_update_reload_and_abort().
• Set reload_on_update=False when calling _abort_if_unique_id_configured().

More details can be found in the core PR.

ha-progress-bar​

A new component replaces mwc-progress-bar in our codebase and is fully themeable. Check out this PR for a fully custom progress bar.

New component specific tokens:

--ha-progress-bar-indicator-color
--ha-progress-bar-indicator-background
--ha-progress-bar-track-color
--ha-progress-bar-track-height
--ha-progress-bar-border-radius
--ha-progress-bar-animation-duration
--ha-progress-bar-indicator-highlight-image
--ha-progress-bar-indicator-highlight-width
--ha-progress-bar-indicator-highlight-height

ha-switch​

ha-switch was migrated to webawesome. It now has many CSS properties to make customization easier. We also removed some tokens from the old switch:

Removed tokens:

--switch-unchecked-button-color
--switch-unchecked-track-color
--switch-unchecked-color
--switch-checked-button-color
--switch-checked-track-color
--switch-checked-color

New component specific tokens:

--ha-switch-size
--ha-switch-thumb-size
--ha-switch-width
--ha-switch-background-color
--ha-switch-thumb-background-color
--ha-switch-background-color-hover
--ha-switch-thumb-background-color-hover
--ha-switch-checked-background-color
--ha-switch-checked-thumb-background-color
--ha-switch-checked-background-color-hover
--ha-switch-checked-thumb-background-color-hover
--ha-switch-border-color
--ha-switch-thumb-border-color
--ha-switch-thumb-border-color-hover
--ha-switch-checked-border-color
--ha-switch-checked-thumb-border-color
--ha-switch-checked-border-color-hover
--ha-switch-checked-thumb-border-color-hover
--ha-switch-thumb-box-shadow
--ha-switch-disabled-opacity
--ha-switch-required-marker
--ha-switch-required-marker-offset

ha-checkbox​

ha-checkbox was also migrated to webawesome and got new CSS properties. You can no longer use MDC tokens for it, but we added a set of tokens to customize the new checkbox.

New component specific tokens:

--ha-checkbox-size
--ha-checkbox-border-color
--ha-checkbox-border-color-hover
--ha-checkbox-background-color
--ha-checkbox-background-color-hover
--ha-checkbox-checked-background-color
--ha-checkbox-checked-background-color-hover
--ha-checkbox-checked-icon-color
--ha-checkbox-checked-icon-scale
--ha-checkbox-border-radius
--ha-checkbox-border-width
--ha-checkbox-required-marker
--ha-checkbox-required-marker-offset

ha-textarea​

ha-textarea was migrated to webawesome and got new CSS properties. You can no longer use MDC tokens for it, but we added a set of tokens to customize the new textarea.

The API changed slightly. To make your textarea grow in size, set the resize prop to auto.

ha-adaptive-popover​

You might already know the (fairly new) ha-adaptive-dialog component. It combines a dialog and bottom sheet by showing a dialog on desktop and a bottom sheet on mobile. We added ha-adaptive-popover as the popover counterpart to the adaptive dialog. It shows a popover on desktop and a bottom sheet on mobile. It is based on ha-adaptive-dialog and is currently used in the tile card date picker feature.

Removed ha-fab​

ha-fab was removed, we use just a normal ha-button now, since the position styling was always done from the parent component.

Style updates​

Box shadow tokens​

We added new global box shadow tokens: --ha-box-shadow-s, --ha-box-shadow-m, --ha-box-shadow-l

But we also removed the old box shadow tokens:

--ha-color-shadow-light
--ha-color-shadow-dark
--ha-shadow-offset-x-...
--ha-shadow-blur-...
--ha-shadow-spread-..

Surface colors​

In the next release we plan to change the way we handle surface background colors. The tokens are introduced now but are just used for ha-tooltip.

New tokens:

--ha-color-surface-default
--ha-color-surface-low
--ha-color-surface-lower
--ha-color-surface-default-inverted
--ha-color-surface-low-inverted
--ha-color-surface-lower-inverted

Context groups​

Following context groups have been added:

• registriesContext: contains all registries (device, entity, area, etc)
• internationalizationContext: contains all internationalization related data (locale, localize, etc)
• apiContext: contains all API related methods (callService, callWS, etc)
• connectionContext: contains all connection related data (connection, connected, hassUrl, etc)
• uiContext: contains all UI related data (themes, panels, dockedSidebar, etc)
• configContext: contains all config related data (auth, config, user, etc)

Consume context entry decorators​

In the last blogpost I showed how to use context with @transform. @transform is powerful, but sometimes you only need a single context entry and do not want to define a transform function. To support that, we added decorators that consume a single context entry directly. You pass an array that defines where the entity ID comes from (usually a config property), and the decorator consumes the correct context and maps the entity ID to the correct registry entry. It also watches the defined path and updates the entry when needed.

New decorators:

• @consumeEntityState
• @consumeEntityStates
• @consumeEntityRegistryEntry

sample usage:

@state()
@consumeEntityRegistryEntry({ entityIdPath: ["_config", "entity"] })
_entity?: EntityRegistryDisplayEntry;

We may add more of these decorators in the future, e.g. for areas, devices, etc.

Deprecate contexts​

These contexts are still available, but they can be removed in a future release. Use the new context groups instead.

• connectionSingleContext
• localizeContext
• localeContext
• configSingleContext
• themesContext
• selectedThemeContext
• userContext
• userDataContext
• panelsContext
• authContext

Background​

pyserial has been the de facto serial library in Python for many years and has broad support for all popular platforms. Its API, however, predates asyncio in Python and is sync-only. The pyserial-asyncio package was eventually released to bridge pyserial with asyncio. Unfortunately, pyserial-asyncio development never reached 1.0 stability or cross-platform support, and neither pyserial nor pyserial-asyncio have had PyPI releases in almost five years. We forked pyserial-asyncio and released pyserial-asyncio-fast to fix outstanding issues affecting Core event loop stability.

We developed serialx from the ground up as a modern Python serial library with native sync and async APIs. It is import-compatible with the serial, serial_asyncio, and serial_asyncio_fast modules and allows existing packages to migrate with very minimal changes, if any.

Migration​

The serialx documentation has an extensive migration guide that goes into more detail.

Most packages just need to replace pyserial, pyserial-asyncio, and pyserial-asyncio-fast with serialx in their setup.py or pyproject.toml file and update exception handling to replace broad catching of SerialException with more granular error handling (such as OSError and TimeoutError).

Packages directly constructing a sync serial.Serial() object should migrate to using the serialx.serial_for_url() helper to ensure automatic compatibility with all supported protocols.

Prompt for your agent​

The migration itself is mechanical, paste the following instructions into your agent of choice:

Migrate my code from pyserial, pyserial-asyncio, and pyserial-asyncio-fast to serialx using https://raw.githubusercontent.com/puddly/serialx/refs/heads/dev/docs/how-to/pyserial-migration.md

This mirrors the infrared entity platform and was approved in architecture discussion #1365.

Architecture​

The radio_frequency domain sits between two types of integrations:

• Transmitter integrations (ESPHome, Broadlink, …) implement the RadioFrequencyTransmitterEntity base class to provide hardware-specific RF transmission.
• Consumer integrations (garage door openers, RF remotes, wireless switches, …) use helper functions to send device-specific RF commands through available transmitters.

Users select which transmitter to use during the consumer integration's config flow, filtered by the frequency the device operates on.

Implementing a transmitter integration​

Transmitter integrations provide the radio_frequency platform by subclassing RadioFrequencyTransmitterEntity, declaring their supported_frequency_ranges, and implementing async_send_command:

from rf_protocols import RadioFrequencyCommand
from homeassistant.components.radio_frequency import RadioFrequencyTransmitterEntity

class MyRadioFrequencyTransmitterEntity(RadioFrequencyTransmitterEntity):
    """My RF transmitter."""

    @property
    def supported_frequency_ranges(self) -> list[tuple[int, int]]:
        """Return the list of (min_hz, max_hz) ranges this hardware can transmit on."""
        return [(300_000_000, 348_000_000), (433_050_000, 434_790_000)]

    async def async_send_command(self, command: RadioFrequencyCommand) -> None:
        """Send an RF command."""
        await self._device.transmit(
            frequency=command.frequency,
            modulation=command.modulation,
            timings=command.get_raw_timings(),
        )

The base class tracks the timestamp of the last sent command as the entity state, so transmitter integrations only need to handle the actual transmission.

Building a consumer integration​

Consumer integrations control RF devices by sending commands through a transmitter entity. They don't interact with RF hardware directly. The snippets below are adapted from the honeywell_string_lights integration, which uses the platform to drive a Honeywell String Lights set.

1. Declare the dependency in manifest.json:

{
  "dependencies": ["radio_frequency"]
}

2. Load the device's commands from the rf-protocols library:

from rf_protocols import get_codes

COMMANDS = get_codes("honeywell/string_lights")

Each loaded command exposes the frequency and modulation the device uses, which the config flow needs to filter transmitters.

3. Let the user pick a transmitter in the config flow, using a sample command to filter by the frequency and modulation the device requires:

from rf_protocols import RadioFrequencyCommand
from homeassistant.components.radio_frequency import async_get_transmitters
from homeassistant.exceptions import HomeAssistantError

sample_command: RadioFrequencyCommand = await self.hass.async_add_executor_job(
    COMMANDS.load_command, "turn_on"
)
try:
    transmitters = async_get_transmitters(
        self.hass, sample_command.frequency, sample_command.modulation
    )
except HomeAssistantError:
    return self.async_abort(reason="no_transmitters")

if not transmitters:
    return self.async_abort(reason="no_compatible_transmitters")

Only ModulationType.OOK (on-off keying) is supported right now; later releases can add other modulation types.

4. Send RF commands using the helper function and the stored transmitter entity ID:

from homeassistant.components.radio_frequency import async_send_command

async def async_turn_on(self, **kwargs: Any) -> None:
    """Turn on the light."""
    command = await self.hass.async_add_executor_job(
        COMMANDS.load_command, "turn_on"
    )
    await async_send_command(self.hass, self._transmitter, command)
    self._attr_is_on = True
    self.async_write_ha_state()

RF protocols and codes​

RF protocol encoders and device code sets live outside Home Assistant in the rf-protocols library. Common protocols and well-known device codes should be contributed there. For niche or proprietary protocols, a separate third-party library can also be used.

For full details, see the radio frequency entity documentation.

Previously, you had to send users to create a blank dashboard, edit in YAML mode, and paste in your custom strategy. Now you can register a friendly name, description, and documentation.

To register your strategy, call window.customStrategies.push() with an object containing the following keys:

• type: The strategy type without the custom: prefix, for example "my-demo".
• strategyType: Set to "dashboard" to register a dashboard strategy.
• name: The friendly name of the strategy.
• description (optional): A short description of the strategy.
• documentationURL (optional): A URL to the documentation for the strategy. This is not shown in the strategy UI yet but may in the future.

Example:

window.customStrategies = window.customStrategies || [];
window.customStrategies.push({
  type: "my-demo",
  strategyType: "dashboard",
  name: "My demo dashboard",
  description: "A starter dashboard generated from JavaScript.",
  documentationURL: "https://example.com/my-demo-dashboard",
});

This metadata is separate from the custom element itself. Your strategy still needs to be registered with a tag like ll-strategy-dashboard-my-demo, and users still need the resource loaded before Home Assistant can discover it. You can use HACS for this as other resources can be added, like custom cards.

Take a look at the updated custom strategies documentation with example code and further details.

The legacy (non-config-entry) device tracker platform API is deprecated and will be removed in the Home Assistant 2027.5 release. By the end of the 12-month deprecation period, all remaining legacy device tracker platforms will be removed from the core repository, and custom integrations implementing the legacy API will stop working.

Integrations authors need to update integrations to implement the modern device tracker platform API.

Background​

Config entry device trackers were introduced in May 2019, which means integration authors have had 8 years to migrate integrations when support is removed in May 2027.

As of today (April 2026) most widely used core device tracker integrations have already been migrated.

Note that the most popular integration that has not yet been migrated, xiaomi_miio, has a wide mix of functionality including other things than device tracker.

The proposal to deprecate the legacy device tracker API was approved in architecture proposal 1375.

List of core integrations, sorted by reported use​

The list was generated from https://analytics.home-assistant.io/ in March 2026

Integration                    Installations  API      Type               Details
----------------------------------------------------------------------------------------------------
mobile_app                           415,204  modern   tracker            TrackerEntity
mqtt                                 233,161  modern   tracker            TrackerEntity
zha                                  126,903  modern   scanner            ScannerEntity
ibeacon                               89,099  modern   unknown            BaseTrackerEntity
fritz                                 42,934  modern   scanner            ScannerEntity
ping                                  33,439  modern   scanner            ScannerEntity
unifi                                 33,136  modern   scanner            ScannerEntity
xiaomi_miio                           12,866  legacy   scanner            async_scan_devices
nmap_tracker                           7,397  modern   scanner            ScannerEntity
icloud                                 5,772  modern   tracker            TrackerEntity
freebox                                5,312  modern   scanner            ScannerEntity
asuswrt                                4,686  modern   scanner            ScannerEntity
tile                                   4,212  modern   tracker            TrackerEntity
renault                                3,646  modern   tracker            TrackerEntity
private_ble_device                     3,231  modern   unknown            BaseTrackerEntity
keenetic_ndms2                         3,080  modern   scanner            ScannerEntity
owntracks                              3,022  modern   tracker            TrackerEntity
snmp                                   2,923  legacy   scanner            async_scan_devices
devolo_home_network                    2,910  modern   scanner            ScannerEntity
tesla_fleet                            2,798  modern   tracker            TrackerEntity
netgear                                2,782  modern   scanner            ScannerEntity
mikrotik                               2,761  modern   scanner            ScannerEntity
tplink_omada                           2,708  modern   scanner            ScannerEntity
starlink                               2,250  modern   tracker            TrackerEntity
tractive                               2,144  modern   tracker            TrackerEntity
volvo                                  2,077  modern   tracker            TrackerEntity
husqvarna_automower                    1,924  modern   tracker            TrackerEntity
tessie                                 1,562  modern   tracker            TrackerEntity
bluetooth_le_tracker                   1,011  legacy
traccar_server                           978  modern   tracker            TrackerEntity
huawei_lte                               827  modern   scanner            ScannerEntity
gpslogger                                813  modern   tracker            TrackerEntity
teslemetry                               720  modern   tracker            TrackerEntity
traccar                                  609  modern   tracker            TrackerEntity
luci                                     590  legacy   scanner            scan_devices
subaru                                   502  modern   tracker            TrackerEntity
mysensors                                474  modern   tracker            TrackerEntity
starline                                 460  modern   tracker            TrackerEntity
geofency                                 443  modern   tracker            TrackerEntity
google_maps                              389  legacy
locative                                 378  modern   tracker            TrackerEntity
opnsense                                 355  legacy   scanner            scan_devices
fing                                     266  modern   scanner            ScannerEntity
ruckus_unleashed                         232  modern   scanner            ScannerEntity
synology_srm                             193  legacy   scanner            scan_devices
unifi_direct                             190  legacy   scanner            scan_devices
mqtt_json                                182  legacy
vodafone_station                         166  modern   scanner            ScannerEntity
xiaomi                                   143  legacy   scanner            scan_devices
demo                                     141  legacy
ubus                                     111  legacy   scanner            scan_devices
bt_smarthub                               95  legacy   scanner            scan_devices
aprs                                      93  legacy
nrgkick                                   81  modern   tracker            TrackerEntity
ddwrt                                     79  legacy   scanner            scan_devices
fressnapf_tracker                         74  modern   tracker            TrackerEntity
linksys_smart                             69  legacy   scanner            scan_devices
fortios                                   53  legacy   scanner            scan_devices
swisscom                                  51  legacy   scanner            scan_devices
tomato                                    45  legacy   scanner            scan_devices
quantum_gateway                           42  legacy   scanner            scan_devices
aruba                                     24  legacy   scanner            scan_devices
meraki                                    24  legacy
sky_hub                                   22  legacy   scanner            async_scan_devices
ituran                                    19  modern   tracker            TrackerEntity
cisco_ios                                 10  legacy   scanner            scan_devices
upc_connect                               10  legacy   scanner            async_scan_devices
cisco_mobility_express                     6  legacy   scanner            scan_devices
arris_tg2492lg                             2  legacy   scanner            async_scan_devices
bbox                                       1  legacy   scanner            scan_devices
actiontec                                  0  legacy   scanner            scan_devices
autoskope                                  0  modern   tracker            TrackerEntity
bt_home_hub_5                              0  legacy   scanner            scan_devices
cppm_tracker                               0  legacy   scanner            scan_devices
fleetgo                                    0  legacy
hitron_coda                                0  legacy   scanner            scan_devices
lojack                                     0  modern   tracker            TrackerEntity
thomson                                    0  legacy   scanner            scan_devices

See the architecture discussion for the full background.

Why​

Previously, each integration used its own string for the "doorbell was pressed" event — ding, ring, doorbell_chime, single_press, etc. This inconsistency made it impossible to build generic doorbell automations that work across all integrations.

The new DoorbellEventType.RING standard event type solves this by ensuring every doorbell integration fires a common ring event when the doorbell is pressed.

What to do​

Import DoorbellEventType from homeassistant.components.event and include DoorbellEventType.RING in your doorbell entity's event_types. Fire it whenever the doorbell is pressed:

from homeassistant.components.event import DoorbellEventType, EventDeviceClass, EventEntity


class MyDoorbellEvent(EventEntity):

    _attr_device_class = EventDeviceClass.DOORBELL
    _attr_event_types = [DoorbellEventType.RING]

    @callback
    def _async_handle_event(self) -> None:
        """Handle the doorbell press event."""
        self._trigger_event(DoorbellEventType.RING)
        self.async_write_ha_state()

Additional custom event types (e.g., double_press, long_press) are still allowed alongside the standard ring type.

Doorbell entities that do not include DoorbellEventType.RING will log a deprecation warning and will stop working in Home Assistant 2027.4.

For full details, see the event entity documentation.

Setting an entity ID with the wrong domain will log a deprecation warning and will stop working in Home Assistant 2027.5.

In most cases, integrations should not set entity_id at all — Home Assistant will generate it automatically.

What changed and why​

The old builder ran every architecture build inside a single privileged Docker-in-Docker container using QEMU emulation. This was slow, required elevated privileges, and those who were already familiar with Docker needed to learn how to use the custom Home Assistant's builder container. The old builder also had unnecessary maintenance overhead. Today, what the builder does can be fully replaced with Docker BuildKit, which is natively supported on GitHub Actions runners and has built-in multi-arch support with QEMU emulation if needed.

For your CI, the replacement is a set of focused composite GitHub Actions that delegate building to the runner's native Docker with Docker BuildKit. Outside the CI, the migration means that your Dockerfile is now the single source of truth for building your app image, and you can use docker build directly to build and test your app locally without needing to use the builder container.

Migration process​

The migration has two parts: updating your Dockerfiles and updating your GitHub Actions workflows.

Update Dockerfiles​

The new build workflow doesn't use build.yaml anymore. Move the content into your Dockerfile as follows:

• build_from - replace the build_from key in build.yaml with a FROM statement in your Dockerfile:

  FROM ghcr.io/home-assistant/base:latest
  

  As the base images are now published as multi-platform manifests, there is usually no need to define per-arch base images anymore. The build-image action still supplies BUILD_ARCH as a build argument though, so you can use that in your Dockerfile if you need to use it in the template for the base image name.

• labels - move any custom Docker labels directly into your Dockerfile with a LABEL statement:

  LABEL \
      org.opencontainers.image.title="Your awesome app" \
      org.opencontainers.image.description="Description of your app." \
      org.opencontainers.image.source="https://github.com/your/repo" \
      org.opencontainers.image.licenses="Apache License 2.0"
  

  If you are creating a custom workflow, note that the legacy builder used to add the io.hass.type, io.hass.name, io.hass.description, and io.hass.url labels automatically. The new actions do not infer these values, so add them explicitly via the labels input of the build-image (or similar) action.

• args - move custom build arguments into your Dockerfile as ARG definitions with default values:

  ARG MY_BUILD_ARG="default-value"
  

  Default values in ARG replace what was previously supplied via build.yaml's args dictionary. They can still be overridden at build time with --build-arg if needed.

With the content of build.yaml migrated, you can delete the file from your repository.

Update GitHub Actions workflows​

Remove any workflow steps using home-assistant/builder@master and replace them with the new composite actions. See the example workflow in our example app repository for a complete working example. Alternatively, use the individual actions in a more custom workflow as needed.

Image naming​

The preferred way to reference a published app image is now the generic (multi-arch) name without an architecture prefix:

# config.yaml
image: "ghcr.io/my-org/my-app"

The {arch} placeholder (e.g. ghcr.io/my-org/{arch}-my-app) is still supported as a compatibility fallback, but it's encouraged to use the generic name and let the manifest handle the platform resolution.

Local builds​

After updating your Dockerfile, you can use docker build to build the app image directly - you can refer to Local app testing for more details.

Apps built locally by Supervisor​

For backward compatibility, Supervisor still reads build.yaml file if it's present and populates the image build arguments with values read from this file. This will produce warnings and eventually be removed in the future, so it's recommended to migrate to the new Dockerfile-based approach as described above.

See the architecture discussion for the full background.

Architecture​

The infrared domain sits between two types of integrations:

• Emitter integrations (ESPHome, Broadlink, …) implement the InfraredEntity base class to provide hardware-specific IR transmission.
• Consumer integrations (LG, Samsung, Daikin, …) use helper functions to send device-specific IR commands through available emitters.

Users select which emitter to use during the consumer integration's config flow.

Implementing an emitter integration​

Emitter integrations provide the infrared platform by subclassing InfraredEntity and implementing async_send_command. The command's get_raw_timings() method returns protocol-agnostic timing data that the hardware can transmit:

from homeassistant.components.infrared import InfraredCommand, InfraredEntity

class MyInfraredEntity(InfraredEntity):
    """My IR transmitter."""

    async def async_send_command(self, command: InfraredCommand) -> None:
        """Send an IR command."""
        timings = [
            interval
            for timing in command.get_raw_timings()
            for interval in (timing.high_us, -timing.low_us)
        ]
        await self._device.transmit(
            carrier_frequency=command.modulation,
            timings=timings,
        )

The raw protocol-agnostic timings should be converted to the specific format required by the hardware.

Building a consumer integration​

Consumer integrations control IR devices by sending commands through an emitter entity. They don't interact with IR hardware directly.

1. Declare the dependency in manifest.json:

{
  "dependencies": ["infrared"]
}

2. Let the user pick an emitter in the config flow:

from homeassistant.components import infrared

emitters = infrared.async_get_emitters(hass)
if not emitters:
    return self.async_abort(reason="no_emitters")

3. Send IR commands using the helper function and the infrared-protocols library:

from infrared_protocols.codes.lg.tv import LGTVCode, make_lg_tv_command
from homeassistant.components import infrared

await infrared.async_send_command(
    hass,
    self._infrared_entity_id,
    make_lg_tv_command(LGTVCode.VOLUME_UP),
    context=self._context,
)

IR protocols and codes​

IR protocol encoders and device code sets live outside Home Assistant in the infrared-protocols library. Common protocols (NEC, Samsung, etc.) and well-known device codes should be contributed there. For niche or proprietary protocols, a separate third-party library can also be used.

For full details, see the infrared entity documentation.

ha-input​

We keep migrating our Material Design based components to Web Awesome based. This time we migrated the input components, which leads to an API change but the look and feel stays the same for now.

• ha-input is the successor of ha-textfield
  • ha-textfield API stays but the component is migrated to use ha-input internally and will be removed in 2026.5
  • Also replaces ha-outlined-text-field
• ha-input-search replaces search-input and search-input-outlined
• ha-input-multi replaces ha-multi-textfield
• ha-input-copy replaces copy-textfield

This component also introduces new semantic theme variables for form backgrounds:

--ha-color-form-background: var(--ha-color-neutral-95);
--ha-color-form-background-hover: var(--ha-color-neutral-90);
--ha-color-form-background-disabled: var(--ha-color-neutral-80);

Date picker​

We finally removed the Vue 2 dependency by replacing the date and date range picker with Cally.

Each dialog managed by the dialog manager was only opened once and stayed in the DOM for the lifetime of the application. This causes:

• More memory usage: Dialogs accumulate in the DOM even when not visible
• More bugs because of missing state reset: Dialog state persists between opens, leading to stale data or unexpected behavior

The Solution: DialogMixin​

We implemented a new way of handling dialogs using DialogMixin. With this approach:

• Dialogs are created when opened and destroyed when closed: No need to manually reset the state of the dialog when it is closed
• Closed events are automatically handled: The dialog mixin takes care of cleanup
• Subscribe mixin can now be used in dialogs: Since dialogs are properly destroyed, subscriptions are cleaned up automatically
• Use normal Lit lifecycle methods: Use connectedCallback to initialize when the dialog is opened instead of relying on the showDialog method

Example​

Check out ha-dialog-date-picker for a reference implementation. DialogMixin adds dialog params to this.params if available.

In the Home Assistant frontend, a Context is a way to share data across the component tree without explicitly passing it through every level as a property. Instead of threading the hass object down through multiple layers of components, you can provide specific pieces of data via context and consume them only where needed.

The key benefits of using context over passing the entire hass object are:

• Easier usage: Components can directly consume the data they need without requiring parent components to pass it down. This reduces prop drilling and makes components more self-contained and reusable.
• Reducing unnecessary component re-renders: When a component receives hass as a property, any change to hass triggers a re-render of that component and all its children—even if the component only cares about a small subset of the data. By using context to provide only the specific data a component needs, you ensure that components only re-render when their actual dependencies change, leading to better performance and a more responsive UI.

Introducing LazyContext​

We've introduced a new LazyContext pattern that should replace the traditional subscription-based approach and the usage of the SubscribeMixin. Previously, components would subscribe to data sources and manage subscription lifecycles manually, often leading to boilerplate code and potential memory leaks if subscriptions weren't properly cleaned up.

LazyContext simplifies this by:

• Lazy loading: Data is only fetched when a component actually consumes the context
• Automatic cleanup: Subscriptions are managed automatically
• Shared state: Multiple components consuming the same context share a single subscription
• Optimized re-renders: Only components that consume the context re-render when data changes

This approach centralizes data-fetching logic and makes it easier to reason about when and how data flows through your application.

Examples​

Defining a LazyContext​

To define a lazy context, use LazyContextProvider and provide a fetch function:

new LazyContextProvider(this, {
  context: labelsContext,
  subscribeFn: (connection, setValue) => subscribeLabelRegistry(connection, setValue),
})

Consuming a context with lit​

To consume a context in a component, use the @consume decorator:

@state()
@consume({ context: labelsContext, subscribe: true })
private _labels?: LabelRegistryEntry[];

Check out the updated custom card example to use it in vanilla JS: Custom card example.

Using @transform for derived Data​

Only available within the home-assistant frontend codebase

The @transform decorator allows you to derive data from a context value, ensuring your component only re-renders when the transformed value actually changes.

@state()
@consume({ context: statesContext, subscribe: true })
@transform({
  transformer: function (this: HuiButtonCard, entityStates: HassEntities) {
    return this._config?.entity ? entityStates?.[this._config?.entity] : undefined;
  },
  watch: ["_config"],
})
private _stateObj?: HassEntity;

With @transform, even if the full states object updates, your component will only re-render if the transformed result (_stateObj) actually changes. The watch option allows you to specify additional properties that should trigger re-evaluation of the transformer function—in this case, when _config changes, the transformer runs again to extract the correct entity state.

class ExampleBackupAgent(BackupAgent):

    async def async_upload_backup(
        self,
        *,
        open_stream: Callable[[], Coroutine[Any, Any, AsyncIterator[bytes]]],
        backup: AgentBackup,
        on_progress: OnProgressCallback,
        **kwargs: Any,
    ) -> None:
        """Upload a backup."""
        ...
        bytes_uploaded = 0
        async for chunk in await open_stream():
            await do_upload(chunk)
            bytes_uploaded += len(chunk)
            on_progress(bytes_uploaded=bytes_uploaded)
        ...

The backup manager uses these progress reports to fire UploadBackupEvent events, enabling the frontend to display real-time upload progress to the user.

Check the backup agent documentation for more details.

Local brand images for custom integrations​

Add a brand/ directory to your custom integration with your icon and logo files:

custom_components/my_integration/
├── __init__.py
├── manifest.json
└── brand/
    ├── icon.png
    └── logo.png

The following image filenames are supported:

• icon.png / dark_icon.png
• logo.png / dark_logo.png
• icon@2x.png / dark_icon@2x.png
• logo@2x.png / dark_logo@2x.png

Local brand images automatically take priority over images from the brands CDN. That's it — no extra configuration needed.

For more details, see the integration file structure documentation.

Brand images now served through a local API​

To make local brand images possible, all brand images are now served through the Home Assistant local API instead of being fetched directly from the CDN by the browser.

A new brands system integration proxies brand images through two endpoints:

• /api/brands/integration/{domain}/{image} — Integration icons and logos
• /api/brands/hardware/{category}/{image} — Hardware images

Images are cached locally on disk and served with a stale-while-revalidate strategy, so they remain available during internet outages.

Impact on the frontend​

The brandsUrl() and hardwareBrandsUrl() helpers in src/util/brands-url.ts now return local API paths instead of CDN URLs. If your custom card or panel uses these helpers, no changes are needed.

If you are constructing brand image URLs manually, update them:

// Old
const url = `https://brands.home-assistant.io/_/${domain}/icon.png`;

// New
import { brandsUrl } from "../util/brands-url";
const url = brandsUrl({ domain, type: "icon" });

These endpoints require authentication. The brandsUrl() helper handles this automatically by appending an access token. If you construct URLs manually, obtain a token via the brands/access_token WebSocket command and append it as a token query parameter.