Component updates​

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.

Summary​

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.

The BrowseMediaSource class in the media_source integration has been tightened up. The domain parameter is now a required str instead of str | None, and the special "list every media source" root node has moved to its own class, RootBrowseMediaSource.

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.

Summary​

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."""
        ...

As of Home Assistant 2026.4, the hass object exposes a formatEntityName helper. It is the same function used by the built-in cards (tile card, entity rows, ...) to compute the display name of an entity from its registry context (entity, device, area, floor). Custom cards can use it to produce names that stay consistent with the rest of the dashboard.

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.

In the future, the MQTT publish API will require explicit values for qos and retain. Passing None for either argument will no longer be supported. Custom integrations should update their code to accept the defaults, or pass valid typed arguments. The fallbacks of None to a valid value for qos and retain will stop working with HA Core 2027.6.

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 MQTT publish API now supports setting a message expiry interval. Previously, retained messages were stored by the broker until they were replaced or explicitly cleared. With a message_expiry_interval set (in seconds), a published message — including a retained one — will automatically expire after the specified interval. This option is only supported when using MQTT protocol version 5; it is ignored when using earlier protocol versions.

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."""

As of Home Assistant Core 2026.6, using a config entry listener together with any reloading methods in a config flow is deprecated and will result in an error from 2026.12.

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.

Component updates​

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

Last release we introduced the lazy context and we wanted to use hass context and lazy context more in favor of passing the hass object. We found that small tasks often required subscribing to many contexts, so we grouped Hass contexts into logical groups.

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