ha-split-panel​

We added ha-split-panel, a Home Assistant wrapper around the Web Awesome split panel component.

Use it when a Home Assistant page, dialog, or tool needs a resizable two-pane layout. Custom card authors can use Home Assistant frontend components, but internal Home Assistant UI APIs may change.

<ha-split-panel position="40" snap="50%">
  <div slot="start">Editor</div>
  <div slot="end">Preview</div>
</ha-split-panel>

New component-specific tokens:

--ha-split-panel-divider-width
--ha-split-panel-divider-hit-area
--ha-split-panel-min
--ha-split-panel-max
--ha-split-panel-grip-display

ha-tile-info updates​

ha-tile-info gained more layout controls for custom cards and tile-like surfaces.

New component-specific tokens:

--ha-tile-info-gap
--ha-tile-info-min-height
--ha-tile-info-primary-min-height
--ha-tile-info-primary-line-clamp

Use --ha-tile-info-primary-line-clamp when the primary text should wrap to more than one line, and use the min-height tokens to keep rows aligned when some tiles have secondary text and others do not.

Form and selector updates​

Conditional ha-form fields​

ha-form schemas now support conditional field visibility with visible.

[
  {
    name: "advanced",
    selector: { boolean: {} },
  },
  {
    name: "advanced_name",
    visible: { field: "advanced", value: true },
    selector: { text: {} },
  },
]

Supported operators are:

"eq"
"not_eq"
"in"
"not_in"
"exists"
"not_exists"

You can also combine conditions with and, or, and not.

Hidden fields are not rendered and are skipped during validation, so use visible instead of custom frontend-only hiding logic when a form field depends on another value.

Selector additions​

The text selector now supports HTML pattern validation:

{
  text: {
    pattern: "[a-z0-9_]+",
    validation_message: "Use lowercase letters, numbers, and underscores",
  },
}

This works for both single-value and multiple-value text selectors.

Entity selectors can now filter by properties of the entity's device:

{
  entity: {
    filter: {
      domain: "sensor",
      device: {
        manufacturer: "Home Assistant",
        model: "Connect ZBT-1",
      },
    },
  },
}

A new ui_clock_date_format selector was also added for the clock card date format editor.

Lovelace updates​

state_color is moving to color​

The entities and glance cards now support color as the replacement for state_color.

Before:

type: entities
state_color: true
entities:
  - light.kitchen

After:

type: entities
color: state
entities:
  - light.kitchen

Use color: state for the old state_color: true behavior, and color: none for state_color: false.

Custom panels and apps​

Safe-area handling​

Custom panels and add-on app iframes now get safe-area padding by default, so content stays clear of notches, status bars, and home indicators.

Custom panels that already handle safe areas themselves can opt out:

panel_custom:
  - name: my-panel
    module_url: /local/my-panel.js
    handle_safe_area: true

For iframe-based custom panels, Home Assistant forwards the resolved safe-area values into the iframe document as CSS variables:

--safe-area-inset-top
--safe-area-inset-right
--safe-area-inset-bottom
--safe-area-inset-left

Add-on app iframes can also opt into managing the safe area themselves when subscribing to Home Assistant properties:

window.parent.postMessage(
  {
    type: "home-assistant/subscribe-properties",
    handleSafeArea: true,
  },
  "*"
);

The properties message then includes safeAreaInsets.

Context and editor infrastructure​

Global dirty state​

DirtyStateProviderMixin now also publishes a global dirty state.

When any connected dirty-state provider has unsaved changes, window.isDirtyState is set and Home Assistant fires a dirty-state-changed event.

window.addEventListener("dirty-state-changed", (ev) => {
  console.log(ev.detail.isDirty);
});

This is useful for shared infrastructure that needs to avoid disrupting active editors or dialogs with unsaved changes.

See the architecture discussion for the full background.

Why​

Previously, each integration picked its own strings for button interactions — single, click, hold, double_press, and so on. This inconsistency made it impossible to build generic button automations that work across integrations, and prevented the frontend from offering meaningful trigger suggestions.

The new ButtonEventType standard event types solve this by giving every button integration a shared vocabulary for the common interactions.

The event types​

ButtonEventType defines six standard event types:

• ButtonEventType.PRESS_START: the button was pressed down.
• ButtonEventType.PRESS_END: the button was released after a brief press (the standard "click").
• ButtonEventType.LONG_PRESS_START: the button was held past a duration threshold.
• ButtonEventType.LONG_PRESS_END: the button was released after a long hold.
• ButtonEventType.MULTI_PRESS_ONGOING: an intermediate press in a multi-press sequence was detected.
• ButtonEventType.MULTI_PRESS_END: a multi-press sequence completed.

The MULTI_PRESS_ONGOING and MULTI_PRESS_END events include a multi_press_count attribute in their event data (the ATTR_MULTI_PRESS_COUNT constant) with the number of presses.

None of these are mandatory. Unlike the doorbell ring event, there is no required type here. Each integration maps only the interactions its hardware can actually produce, and lists just those in event_types.

What to do​

Import ButtonEventType from homeassistant.components.event and include the types your device supports in the entity's event_types. Fire them as the interactions happen:

from homeassistant.components.event import (
    ATTR_MULTI_PRESS_COUNT,
    ButtonEventType,
    EventDeviceClass,
    EventEntity,
)


class MyButtonEvent(EventEntity):

    _attr_device_class = EventDeviceClass.BUTTON
    _attr_event_types = [
        ButtonEventType.PRESS_END,
        ButtonEventType.LONG_PRESS_END,
        ButtonEventType.MULTI_PRESS_END,
    ]

    @callback
    def _async_handle_multi_press(self, count: int) -> None:
        """Handle a completed multi-press sequence."""
        self._trigger_event(
            ButtonEventType.MULTI_PRESS_END,
            {ATTR_MULTI_PRESS_COUNT: count},
        )
        self.async_write_ha_state()

Single-event devices​

If a device only emits a single event per interaction, with no separate press and release, map it to the matching _end type (PRESS_END for short presses, LONG_PRESS_END for holds, and so on). This keeps the "button was pressed" trigger consistent across devices without synthesizing events the hardware never sends.

No migration required​

This change only adds the shared constants; nothing is deprecated and no integration is forced to migrate. Custom event types are still allowed alongside the standard ones. Adopt ButtonEventType when it fits your device.

For full details, see the event entity documentation.

A device is now owned by a single config entry, and by a single (or no) config subentry. Devices are no longer merged across integrations: a physical device supported by several integrations is now represented by one device per config entry instead of a single shared device.

Devices which were previously tied to multiple config entries are split into one device per config entry when the device registry is loaded. The entity registry is updated so entities point to the correct device.

Most integrations don't interact directly with the device registry and don't need any changes. Integrations which interact with it directly need to handle the deprecations listed below.

This is implemented in core PR #175785, the rationale is described in architecture proposal home-assistant/architecture#1226. The changes land in Home Assistant Core 2026.8.

Background​

Until now, a physical device supported by several integrations has been merged into a single, shared device. This was achieved by identifying devices by connections and identifiers which are globally unique, so that for example a device tracker and a native integration referring to the same MAC address end up on the same device.

This causes a few problems:

• There's no single source of truth for device information such as name or model; conflicting values are discarded instead of preserved.
• Users get a confusing experience where a device page contains a hodgepodge of entities from multiple integrations.
• There are long-standing bugs where modifying the connections and identifiers of a device causes multiple devices to end up with the same connections, violating the original design of the device registry.

The new behavior is achieved by making identifiers and connections unique per config entry instead of globally unique.

Deprecations​

Using the deprecated functionality below logs a warning at runtime. Unless noted otherwise, deprecated functionality remains supported until Home Assistant Core 2027.8.

DeviceEntry.config_entries​

Deprecated, use DeviceEntry.config_entry_id instead. The property is kept as a compatibility shim which returns a set with the device's single config entry.

DeviceEntry.config_entries_subentries​

Deprecated, use DeviceEntry.config_entry_id and DeviceEntry.config_subentry_id instead. The property is kept as a compatibility shim.

DeviceEntry.primary_config_entry​

Deprecated, use DeviceEntry.config_entry_id instead. A device now belongs to a single config entry, which is its primary config entry.

Reading config entries of a composite device​

DeviceEntry.config_entries, DeviceEntry.config_entries_subentries and DeviceEntry.primary_config_entry are only deprecated for ordinary devices, which belong to a single config entry. They are not deprecated when interacting with a synthesized composite device, the read-only device the backwards compatibility resolution returns for a pre-migration composite device id (see Backwards compatibility). Such a device spans several config entries, which config_entry_id and config_subentry_id can't represent, so these three properties, which report the union across the split devices, remain the way to read that information.

DeviceInfo["via_device"] and DeviceRegistry.async_get_or_create(via_device=...)​

Deprecated, use via_device_id instead. Because identifiers are only unique per config entry, an identifier pair no longer unambiguously points at a single device, which is why via_device is deprecated.

Passing both via_device and via_device_id raises HomeAssistantError.

DeviceRegistry.async_update_device() config entry parameters​

The add_config_entry_id, add_config_subentry_id, remove_config_entry_id and remove_config_subentry_id parameters are all deprecated. A device belongs to a single config entry and subentry, so adding and removing config entries is no longer meaningful; a device is instead moved or removed.

To move a device to another config entry or subentry, pass the new new_config_entry_id and new_config_subentry_id parameters:

device_registry.async_update_device(
    device.id,
    new_config_entry_id=config_entry.entry_id,
    new_config_subentry_id=subentry.subentry_id,
)

Moving a device with the old parameters took the integration several async_update_device calls, adding the device to the new config entry and subentry and then removing it from the old ones, with a separate case for a device that only changed subentry within the same config entry. The single call shown above replaces all of that. In addition, the device registry now clears a CONFIG_ENTRY disable when a device is moved to an enabled config entry, so the integration no longer has to carry the disabled_by flag across the move by hand.

Relatedly, async_update_device now validates the disabled_by flag against the owning config entry's disabled state. Setting disabled_by=None for a device on a disabled config entry, or disabled_by=DeviceEntryDisabler.CONFIG_ENTRY for a device on an enabled config entry, is inconsistent; such a value is ignored and logged now, and will raise from Home Assistant Core 2027.8.

Core integrations have been updated as examples: openai_conversation in PR #176662, scrape in PR #176663, waqi in PR #176664 and wolflink in PR #176665.

To remove a device, call DeviceRegistry.async_remove_device():

device_registry.async_remove_device(device.id)

Core integrations have been updated to remove devices this way in PRs #176669, #176671, #176672 and #176673.

DeviceRegistry.async_get_device()​

Deprecated. Identifiers and connections are only unique per config entry, so a lookup by identifiers or connections can by design match more than one device, and what async_get_device returns is therefore ambiguous.

When the owning config entry is known, look the device up scoped to that config entry with the new methods DeviceRegistry.async_get_device_by_identifier() or DeviceRegistry.async_get_device_by_connection(). Each takes a single identifier or connection tuple plus the config entry id, so the lookup can no longer be ambiguous:

# Before
device = device_registry.async_get_device(identifiers={(DOMAIN, serial_number)})
# After
device = device_registry.async_get_device_by_identifier(
    (DOMAIN, serial_number), entry.entry_id
)

Inside an entity, prefer self.device_entry over a registry lookup. If you genuinely need every device matching a key, possibly across config entries, use DeviceRegistry.async_get_devices(), which returns a list.

Core integrations are migrated to the new methods, heos in core PR #176932 is an example.

During the deprecation period, async_get_device resolves an ambiguous lookup as described in Backwards compatibility below. Note that this backwards-compatible resolution only happens through the DeviceRegistry lookup methods such as async_get() and async_get_device(); interacting with the devices container directly, for example DeviceRegistry.devices.get(device_id), does not synthesize a composite device.

Adding a helper config entry to another integration's device​

Helper integrations must not add their config entry to the source entity's device or to a user-selected device, they should link their entities to the device instead. This is a direct consequence of the change described here: a device now belongs to a single config entry, so a helper config entry can no longer be added to a device owned by another integration.

This was announced last year in Updated guidelines for helper integrations linking to other integration's device, and stops working in Home Assistant Core 2026.8.

helpers.device.async_device_info_to_link_from_entity() and async_device_info_to_link_from_device_id()​

Both helpers now always return None.

They returned a DeviceInfo carrying another device's identifiers and connections, which implicitly added the caller's config entry to that device. A device with a single config entry can't represent that, it would silently fork a duplicate device instead.

Link the helper entity to the device by setting self.device_entry in the entity's constructor instead:

self.device_entry = async_entity_id_to_device(hass, source_entity_id)

The helpers are removed in Home Assistant Core 2027.8.

helpers.helper_integration.async_handle_source_entity_changes(add_helper_config_entry_to_device=...)​

The parameter no longer has any effect and should be removed from the call.

When the source entity moves to another device, async_handle_source_entity_changes now only updates the helper entity to link to the new device, it no longer removes the helper config entry from the old device and adds it to the new one.

Passing the parameter is accepted until Home Assistant Core 2027.8, and logs a warning.

Cleaning up helper devices​

The helper used to clean up a helper integration's devices from a config entry migration step has been renamed from async_remove_helper_config_entry_from_source_device to homeassistant.helpers.helper_integration.async_remove_helper_devices in core PR #176714. The old name is kept as a deprecated alias which keeps working until Home Assistant Core 2027.8. The new signature is:

def async_remove_helper_devices(
    hass: HomeAssistant,
    *,
    helper_config_entry_id: str,
    source_device_id: str | None,
    remove_all_devices: bool = False,
    keep_device_ids: Collection[str] = (),
) -> None:

helpers.device.async_remove_stale_devices_links_keep_entity_device() and async_remove_stale_devices_links_keep_current_device()​

Both are now no-ops. Call async_remove_helper_devices with remove_all_devices=True from the helper's async_setup_entry instead:

async_remove_helper_devices(
    hass,
    helper_config_entry_id=entry.entry_id,
    source_device_id=entry.options.get(CONF_DEVICE_ID),
    remove_all_devices=True,
)

The template helper has been migrated as an example in core PR #176900. The functions are removed in Home Assistant Core 2027.8.

Devices can only have a single config subentry​

A device can no longer be tied to more than one config subentry. This is a breaking change without a backwards compatibility shim; integrations which attach several subentries to the same device must create one device per subentry.

Example: telegram_bot​

The telegram_bot integration has been adjusted for this in core PR #176606, which can be used as an example.

It previously had a single bot device shared by every chat, with each chat's subentry attached to that same device. It now creates an individual device per chat, linked to the bot device as a via device. A config entry migration moves each chat's notify entity onto its own device and strips the chat subentries from the bot device, leaving the bot device with no subentry.

Note that the PR was written before via_device_id was added, new code should use via_device_id instead of via_device.

When child devices are introduced, integrations which model this with a via device should migrate to child devices instead.

Linking an entity to a split device​

A pre-migration composite device id no longer refers to a real device. Attempting to link an entity to such an id, by passing it to EntityRegistry.async_get_or_create(device_id=...) or EntityRegistry.async_update_entity(device_id=...), is ignored with a logged warning rather than applied. A new entity is then created with no device, and an existing entity keeps its current device. Passing a genuinely non-existent device id still raises ValueError as before.

Entities whose stored device is a composite device with no split owned by the entity's config entry are detached from the device when the registry is loaded; the owning integration is expected to re-link them.

Link entities to one of the split devices instead, looking it up with async_get_device_by_identifier or async_get_device_by_connection.

Device registry events​

Splitting a pre-migration composite device happens when the registry is loaded from storage, before any listeners run, so it emits no EVENT_DEVICE_REGISTRY_UPDATED events; devices are already split at startup.

Two things change for integrations which subscribe to EVENT_DEVICE_REGISTRY_UPDATED, or use async_track_device_registry_updated_event, and inspect the payload:

• The changes dict of an update event reports a device move with the keys config_entry_id and config_subentry_id, replacing the previous config_entries and config_entries_subentries.
• Updating or removing a pre-migration composite device id forwards the operation to each split device, so one event is fired per split device rather than a single event for the composite id.

A device now belongs to a single config entry, so it can no longer lose one config entry while staying around for another. Integrations which previously watched update events for a change to the config_entries or config_entries_subentries keys, typically to detect their config entry being removed from a device shared with another integration, probably only need to handle remove events now: a device losing its config entry means the device is removed.

Backwards compatibility​

Splitting devices changes assumptions which custom integrations may rely on, and device ids which are stored in automations and scripts no longer exist as devices. To soften that, the device registry makes a best-effort attempt to keep unmodified custom integrations working, by resolving a pre-migration composite device id to the devices it was split into.

This is best-effort, not a guarantee. The shims can't cover every way a custom integration interacts with the device registry, and an operation which is ambiguous across the split devices can't be applied at all. An AI-assisted analysis of 462 custom integrations interacting directly with the device registry suggests at least 90% are expected to work unaffected, which also means some will not. Please migrate your integration to the new API rather than relying on these shims; they are removed in Home Assistant Core 2027.8.

During the deprecation period:

• DeviceRegistry.async_get() synthesizes a read-only restored composite device when passed the id of a pre-migration composite device. Its identifiers, connections and config entries are the union of the split devices'. The synthesis only happens in async_get(); interacting with the devices container directly, for example DeviceRegistry.devices.get(device_id), does not synthesize a composite and returns None for a pre-migration composite device id.
• DeviceRegistry.async_get_device() resolves a lookup by identifiers or connections matching several config entries to a single device when possible, preferring the device whose config entry domain matches the looked-up identifier. If the remaining matches are the splits of one pre-migration composite device, a read-only composite spanning them is returned. For independent devices sharing an identifier or connection, a device owned by the calling integration is preferred, falling back to the first match.
• DeviceRegistry.async_update_device() and DeviceRegistry.async_remove_device() forward the call to each of the split devices. Arguments which rewrite a device's identity or move it are ambiguous across the split devices; they are ignored and reported to the offending integration.
• Entity registry get_entries_for_device_id() and async_entries_for_device() expand a pre-migration composite device id to the entities of the devices it was split into.
• Actions targeting a pre-migration composite device id trickle down to the split devices.
• User customizations (area, floor, labels, name) are kept when a device is split.

A new method DeviceRegistry.async_get_devices_for_composite_device_id() returns the devices a pre-migration composite device was split into. DeviceRegistry.async_is_composite_device_id() returns whether a device id is a pre-migration composite device id, that is, an id which was split into one device per config entry and no longer refers to a registered device.

Today, we are publishing the Open Home Foundation AI Policy. It applies to all Open Home Foundation projects, including every repository in the home-assistant and home-assistant-libs GitHub organizations.

The policy boils down to a few points:

• AI tools are welcome as an aid. You remain responsible for everything you submit.
• Autonomous agents are not allowed to contribute. Pull requests and issues that were created autonomously will be closed.
• You must understand and be able to explain every change you submit, in your own words. This includes answering questions from maintainers yourself, not having an AI do it for you.
• Using AI to improve the grammar or clarity of text you have written yourself is fine. For non-native English speakers this is genuinely useful, and we appreciate the effort.

We are rolling the policy out to every repository in both organizations. Each repository gets an AI_POLICY.md file in its root, and existing contributing guidelines and AGENTS.md files gain a reference to it, so both humans and their AI tools know what we expect.

Read the full policy in the developer documentation. If a contribution does not follow it, it will be closed. If you believe that happened to yours in error, reach out to a maintainer and we will sort it out.

Modbus is everywhere in the modern home: solar inverters, energy meters, heat pumps, and all kinds of industrial equipment that has found its way indoors. Home Assistant has long supported these devices through the YAML-based modbus integration, where users hand-write register maps in their configuration. That integration is not going anywhere, and existing setups keep working. But hand-writing register maps puts the burden of understanding a device's protocol on every user, and it does not fit the config-flow, UI-first direction the rest of Home Assistant has taken.

So we are adding a new way to use Modbus: an integration-based approach, where a device integration owns the device-specific knowledge and the user simply picks their device in the UI, the same as any other integration.

Sharing a connection​

A Modbus connection is a single, exclusive resource: only one party can talk on the bus at a time. A serial (RS-485) bus, or a TCP-to-serial gateway, can carry many devices at once, sometimes from different manufacturers. If two integrations each open their own connection to the same bus, they fight over it, and historically Home Assistant did not support sharing a bus between integrations at all.

The new modbus_connection integration solves this by making a connection something device integrations route through rather than own. The user sets up a connection once in the UI, and modbus_connection keeps it open and manages its lifecycle, including reconnecting after a drop. Device integrations then borrow what they need from that shared connection instead of managing their own. We have revamped the Modbus developer documentation to cover how that works, with example code.

A standalone library​

The connection abstraction underneath modbus_connection lives in modbus-connection, a new library we designed for this purpose and published on PyPI. It is not bound to Home Assistant and can be used standalone in any Python project. It presents a common, backend-neutral interface, so device library authors write against one API regardless of the underlying Modbus implementation, and it ships a device-modelling framework and a pytest plugin to make building and testing a device library straightforward.

This keeps concerns where they belong. A device library is a normal PyPI package that knows how to talk to a specific device, and a consuming integration in Home Assistant wires that library up to a shared connection and exposes entities. Both can be developed and tested independently.

For more background, see our research.

Let's get building​

With these new building blocks in place, it is now possible to turn a collection of YAML configuration for Modbus into manufacturer-specific integrations that people can set up via the UI. If you're (interested in) working on this, stop by the #modbus channel on the Home Assistant Discord and we'll be happy to help.

If you're using an AI agent, you can give it the following prompt:

I want to create a new integration for Home Assistant using the new Modbus Connection integration as documented here: https://developers.home-assistant.io/docs/modbus/introduction

The YAML we want to turn into a device library can be found here: TODO INSERT LOCATION OF MODBUS YAML!

The deliverables of this task are going to be 3 folders:

• Start by creating a device library based on the YAML. Follow https://github.com/Tom-Bom-badil/trovis-modbus/ as an exact example, including how to use component models, all GitHub Actions, helper scripts and README. This library is meant as a standalone device library and should not mention Home Assistant. Look at the source of modbus_connection to figure out all supported fields.

• Create an integration that can be contributed to Home Assistant core that follows this example: https://github.com/home-assistant/core/tree/trovis557x-integration/homeassistant/components/trovis557x

• Create a custom integration version where the device library is vendorized so it is ready to be tested by the community via HACS. Follow this template https://github.com/ludeeus/integration_blueprint

from homeassistant.components.media_player import SearchMedia, SearchMediaQuery

async def async_search_media(
    self, item: MediaSourceItem, query: SearchMediaQuery
) -> SearchMedia:
    """Search media."""
    results = [...]  # list of BrowseMediaSource items
    return SearchMedia(result=results)

To tell the media browser which items can be searched, set the can_search flag to True on the BrowseMediaSource items you return while browsing (typically directories). Other integrations can trigger a search through the new media_source.async_search_media helper.

For more info, see the updated documentation.

The flag existed because the homeassistant start trigger was a pseudo trigger: instead of acting like a real trigger, it relied on the caller of the trigger API passing home_assistant_start=True so that async_initialize_triggers would fire the trigger during startup.

The start trigger has been rewritten to work as a real trigger, so the flag is no longer needed. Callers of async_initialize_triggers should simply stop passing home_assistant_start.

To make the new implementation possible, the rewrite adds HomeAssistant.async_add_startup_job, which registers a job to be called after all listeners to EVENT_HOMEASSISTANT_START have executed, but before EVENT_HOMEASSISTANT_STARTED is fired. This mirrors the approach already used for the homeassistant shutdown trigger, and avoids adding yet another core state and event to the already complex relationship between core states and events.

For more details, see core PR 175160.

• UnitOfDensity enumerator replaces mass over volume CONCENTRATION_*** constants ("g/m³", "mg/m³", "μg/m³", "μg/ft³")
• UnitOfRatio enumerator replaces unit-less ratio CONCENTRATION_*** constants ("ppm", "ppb")

CONCENTRATION_PARTS_PER_CUBIC_METER was only used by a single integration and is deprecated without a replacement unit.

Please note that the use of PERCENTAGE constant is also deprecated when used as a unit of measurement, even if the constant itself is not deprecated.

Component sizes use Web Awesome names​

ha-button, ha-button-toggle-group, and ha-slider now use the short Web Awesome size names.

For ha-button, use:

<ha-button size="s">Save</ha-button>

Supported values are xs, s, m, l, and xl.

For ha-button-toggle-group, use s or m:

<ha-button-toggle-group size="s" .buttons=${buttons}></ha-button-toggle-group>

ha-slider uses s or m.

If your custom card or editor still uses small, medium, or large on these components, migrate them to short values like s, m, or l.

Virtualized lists​

We added two list components for large data sets:

• ha-list-virtualized
• ha-list-selectable-virtualized

Use these when a picker or dialog can render enough rows to affect scrolling or initial render time. The virtualized list renders only the visible rows while keeping the roving-tabindex keyboard navigation from ha-list-base.

Rows expose accessibility metadata with aria-setsize and aria-posinset, so assistive technologies still get the full list position even though only part of the list is in the DOM.

For selectable lists, render ha-list-item-option rows.

Context and editor infrastructure​

Dirty state tracking​

Dialogs and editors now have shared dirty-state infrastructure:

• DirtyStateProviderMixin
• dirtyStateContext
• isDirtyState
• isEffectiveDirtyState

Use DirtyStateProviderMixin for new dialogs or editors that need to block scrim close, enable Save only after edits, or coordinate dirty state with child components.

class MyDialog extends DirtyStateProviderMixin<MyState>()(LitElement) {
  public openDialog() {
    this._initDirtyTracking({ type: "shallow" }, this._state);
  }

  private _stateChanged(state: MyState) {
    this._updateDirtyState(state);
  }
}

isDirtyState is the raw comparison and is usually right for enabling Save. isEffectiveDirtyState can ignore equivalent config output, for example when an editor normalizes an explicit default back to the same effective config.

Related context​

Pages and editors can now publish related context for nearby pickers:

• relatedContext
• fireRelatedContext
• fireEntityRelatedContext

When a card editor, badge editor, automation trace page, or similar surface knows the current entity, device, or area, it can provide that context. Entity pickers and add-element searches can then prioritize related entities, devices, and areas.

fireEntityRelatedContext(this, "light.kitchen");

Clear the context with undefined when the editor no longer has a related item.

Narrow viewport context​

narrowViewportContext exposes whether the main Home Assistant viewport is in the narrow layout.

Components that only need narrow-layout state can consume this context instead of receiving narrow through several layers of properties.

@consume({ context: narrowViewportContext, subscribe: true })
private _narrow!: boolean;

Lovelace updates​

Strategy regeneration control​

Lovelace strategies can now avoid unnecessary regeneration.

Strategies may declare registryDependencies to use the default reference-change check for only the registries they depend on:

static registryDependencies = ["entities", "areas"] as const;

For custom logic, implement shouldRegenerate():

static shouldRegenerate(config, oldHomeAssistant, newHomeAssistant) {
  return oldHomeAssistant.entities !== newHomeAssistant.entities;
}

If neither is provided, strategies keep the previous default behavior and regenerate on changes to entities, devices, areas, or floors.

There have been multiple recent changes to the device tracker entity model:

• The battery_level property has been deprecated
• The location_name property of TrackerEntity has been deprecated
• A new entity base class BaseScannerEntity has been introduced
• Users can associate scanners with other zones than the home zone
• TrackerEntity has a new property in_zones
• BaseScannerEntity and ScannerEntity have a new state attribute in_zones
• A new capability attribute tracking_type has been introduced
• Zones are now calculated by size, then distance to center when calculating the state of TrackerEntity

Details​

Deprecation of battery_level​

The battery_level property has been deprecated in all device tracker base classes, and will stop working in Home Assistant Core 2027.7. Integrations should communicate battery level via a battery sensor instead.

More details can be found in architecture proposal #627

Deprecation of location_name​

The location_name property of TrackerEntity has been deprecated, and will stop working in Home Assistant Core 2027.7.

Integrations with device trackers which do not know or do not want to report the exact coordinates and today use location_name to report the name of a zone should instead report a list of zone entity IDs through the in_zones property. Device trackers which use location_name to give extra context can instead do that via a separate sensor or an extra state attribute.

More details can be found in architecture proposal #1387

Introduction of the BaseScannerEntity base class​

The BaseScannerEntity class should be used by integrations which have scanners which do not track connection to a WLAN or other local network, for example scanners which track connection to a BLE beacon.

Users can associate BaseScannerEntity and ScannerEntity with any zone​

BaseScannerEntity and ScannerEntity store the associated zone as an entity registry option. The base class will set the state of the entity to the name of the associated zone when connected, and the in_zones state attribute to all zones which contain the associated zone.

More details can be found in architecture proposal #1389

Introduction of the in_zones state attribute​

A new state attribute in_zones is present in the state of device tracker entities. The state attribute is automatically calculated by BaseScannerEntity and ScannerEntity. TrackerEntity will derive the in_zones state attribute from the in_zones property if not None, if it is None it will be calculated from the reported location.

The in_zones state attribute is a list of zone entity IDs sorted by size, with the smallest zone first, then by distance to center.

Introduction of the tracking_type capability attribute​

A new capability attribute tracking_type is present in the state of device tracker entities. The state attribute is set to connection by BaseScannerEntity and ScannerEntity and to location by TrackerEntity. Integrations should not override this behavior.

To opt in, add a getEntitySuggestion function to your window.customCards entry. It receives the hass object and the selected entity id, and returns a suggestion (or null if the entity is not supported):

window.customCards.push({
  type: "my-card",
  name: "My Card",
  getEntitySuggestion: (hass, entityId) => {
    if (entityId.split(".")[0] !== "light") {
      return null;
    }
    return {
      config: { type: "custom:my-card", entity: entityId },
    };
  },
});

You can also return an array of suggestions to offer several variants, each with its own label.

Only suggest your card when it makes sense for the entity. Check the domain, device class, or supported features with the hass object, and return null otherwise. Suggesting your card for every entity makes the picker noisy.

See the custom card documentation for the full reference.

ha-radio updates​

ha-radio was removed from our codebase, we use the webawesome based ha-radio-group with ha-radio-option now. No need for a ha-formfield around a ha-radio anymore and you can use the new CSS properties to customize the radio group and options.

New component specific tokens:

--ha-radio-group-required-marker
--ha-radio-group-required-marker-offset

--ha-radio-option-active-color
--ha-radio-option-heigh
--ha-radio-option-toggle-size
--ha-radio-option-border-width
--ha-radio-option-border-color
--ha-radio-option-border-color-hover
--ha-radio-option-background-color
--ha-radio-option-background-color-hover
--ha-radio-option-checked-background-color
--ha-radio-option-checked-icon-color
--ha-radio-option-checked-icon-scale
--ha-radio-option-control-margin

ha-drawer updates​

ha-drawer was updated to use the webawesome drawer component. The API is mostly the same it just uses now --ha-sidebar-width instead of --mdc-drawer-width

top bar​

• ha-top-app-bar was removed entirely.
• ha-top-app-bar-fixed was migrated from MWC to plain Lit.
• ha-two-pane-top-app-bar-fixed was rewritten to extend the new implementation instead of Material base code.
• ha-header-bar was rewritten from a Material top-app-bar styled wrapper to a native Lit component.

The --ha-top-app-bar-width token replaces --mdc-top-app-bar-width.

New decorators​

@consumeLocalize​

Following up on the context entry decorators introduced last release, we added a shortcut for the most common single-field read off internationalizationContext: the localize function.

Before:

@state()
@consume({ context: internationalizationContext, subscribe: true })
@transform<HomeAssistantInternationalization, LocalizeFunc>({
  transformer: ({ localize }) => localize,
})
private _localize!: LocalizeFunc;

After:

@state()
@consumeLocalize()
private _localize!: LocalizeFunc;

Use @consumeLocalize() whenever a component only needs the localize function. For other single-field reads off internationalizationContext (e.g. locale, language), keep using @consume + @transform.

User profile advanced mode is going away, which means integrations can no longer check if advanced mode is enabled or not in data entry flows.

Integrations authors need to update integrations to use an alternative user friendly way to present additional options in the UI, for example group additional options in a section.

FlowHandler.show_advanced_options​

The FlowHandler.show_advanced_options property has been deprecated and will be removed with the release of Home Assistant Core 2027.6. During the deprecation period, FlowHandler.show_advanced_options unconditionally returns True to not make options gated by this flag inaccessible to users.

FlowHandler.context['show_advanced_options']​

There is no longer a show_advanced_options key in FlowHandler.context.

Background​

The Advanced mode toggle in the user profile is a single binary switch that gates a collection of unrelated features across Home Assistant, from app (add-on) visibility (Terminal & SSH) to configuration options and UI elements, and we've been working on removing it during the past year.

For a more in-depth explanation, see roadmap issue #54.

Previously, domain was optional only to represent one edge case: the top-level node returned when browsing media-source:// with no specific source selected. That made the type hint misleading for the 99% case — every actual media source has a domain — and added a None branch that consumers had to think about. Splitting the root into its own class removes that branch.

What changed​

• BrowseMediaSource.__init__ now requires domain: str.
• A new RootBrowseMediaSource class represents the root browse node listing all available media sources. It hardcodes domain=None and identifier=None and uses media-source:// as its content ID.
• media_source.async_browse_media() and MediaSourceItem.async_browse() now return BrowseMediaSource | RootBrowseMediaSource.

Impact on custom integrations​

Most integrations don't need any changes. If you implement a media_source.py platform, you were already passing your own domain to BrowseMediaSource — that keeps working.

You only need to act if:

• You pass domain=None to BrowseMediaSource. This is no longer allowed. Set your integration domain instead.

• You call media_source.async_browse_media() and annotate the result. Update the type hint to BrowseMediaSource | RootBrowseMediaSource, or narrow with isinstance() before using domain-specific attributes:

  from homeassistant.components.media_source import (
      BrowseMediaSource,
      async_browse_media,
  )
  
  result = await async_browse_media(hass, media_content_id)
  if isinstance(result, BrowseMediaSource):
      # result.domain is guaranteed to be a str here
      ...
  

See the updated media source platform documentation for the full reference.

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