Problem statement
In July 2022, Home Assistant introduced a new entity naming model (has_entity_name) to separate device names from entity names, enabling context-aware display throughout the product. The core idea: entities carry only their own name (e.g., "Temperature"), the device name lives in the device registry (e.g., "Living Room Sensor"), and Home Assistant composes the appropriate display name depending on where it appears. On a device page, you see "Temperature." In an entity picker, you see "Living Room Sensor Temperature." On a dashboard card scoped to a specific area, you can omit the area entirely.
The backend migration is largely complete. The majority of config-flow integrations have adopted has_entity_name, and the number continues to grow. It is a Bronze-tier requirement in the Integration Quality Scale, mandatory for all new integrations with no exceptions. Entity name translations, translation placeholders for multi-channel devices, and device-class-based name fallback have all shipped.
The frontend has started to deliver on the original vision. Entity pickers show device and area context (2025.5). Dashboard cards support name composition controls (2025.11). The target picker shows full hierarchical context (2025.11).
However, the architecture underneath is not finished. The frontend still computes display names by stripping the device name prefix from the pre-composed friendly_name attribute using fragile string heuristics (strip_prefix_from_entity_name.ts, compute_entity_name.ts). This approach is locale-unfriendly, breaks when friendly_name has been manually overridden, and caused crashes in 2025.5 when entities had non-string names (frontend #25456, #25671). The companion apps (iOS and Android) rely entirely on the friendly_name state attribute for all native surfaces: widgets, watch complications, CarPlay, Control Center, entity pickers, and notifications. They do not query entity or device registries for structured name components and cannot do context-aware display.
This matters for the "Make Home Assistant More Approachable" goal. Entity naming remains one of the most consistently raised pain points in the community. New users are confused by the relationship between name, friendly_name, entity_id, and the registry. Device names get prepended to entity names creating absurd duplications. Dashboard cards show names that are too long and truncate on mobile. The 2022 vision of "the system just handles naming correctly based on context" is only partially delivered, and the remaining gaps are the ones users feel most acutely.
Completing this migration is also a prerequisite for future work. The ability to edit entity.name directly (instead of the composed friendly_name) depends on the backend exposing structured name components. Context-aware voice assistant responses depend on it. Any future deprecation of the friendly_name attribute depends on all first-party consumers (frontend, companion apps) being migrated off it.
Scope & Boundaries
In scope
- Backend: expose structured name components via the WebSocket API. The backend should provide entity name, device name, and area name as discrete fields to all consumers, so they can compose display names based on context without relying on
friendly_name string manipulation.
- Frontend: replace string-stripping logic with structured name composition. Remove the heuristic-based prefix stripping in
compute_entity_name.ts and strip_prefix_from_entity_name.ts. Frontend PR #30147 ("Simplify entity name computation," opened March 13, 2026, labeled "wait for backend") is the tracking PR for this work.
- Frontend: allow editing
entity.name instead of friendly_name. When a user "renames" an entity, they should be editing the entity's own name field, not the pre-composed friendly_name. This enables the system to continue composing display names correctly after a rename. Architecture discussion #1185 covers this in detail.
- Companion apps: adopt registry-based naming. iOS and Android apps should query entity and device registries for name components and implement context-aware display on native surfaces (widgets, complications, entity pickers, notifications). The
friendly_name attribute remains available for backward compatibility but should no longer be the primary source of truth.
- Maintain backward compatibility for
friendly_name. The friendly_name state attribute continues to be emitted for third-party consumers (custom cards, custom integrations, voice assistants, external tools). No deprecation of friendly_name is in scope for this bet.
Not in scope
- Migrating remaining integrations to
has_entity_name. This is handled through normal Integration Quality Scale enforcement and is not blocked by this work.
- Deprecating or removing the
friendly_name state attribute. That is a future step that depends on this work being complete.
- Bulk entity renaming tools or entity_id refactoring (tracked separately in GitHub Discussions #16 and #2441).
- The MQTT
default_entity_id / object_id deprecation (deadline 2026.4, tracked in core #157241 and related issues).
- Changes to how
entity_id is generated or updated on rename.
Foreseen solution
The work breaks down into three phases that can be partially parallelized.
Phase 1: Backend structured name API
Extend the entity registry WebSocket API to expose the raw name components: entity.name (the entity's own name, which may be None for primary entities), device.name, and area.name as discrete fields. This gives all consumers (frontend, companion apps, voice) the data they need to compose display names contextually. The friendly_name state attribute continues to be computed and emitted as before for backward compatibility.
This phase also includes adding the ability for users to edit the entity's own name (entity.name) through the entity registry, separate from the composed friendly_name. A flag (working name: "use as full name" or similar) allows entities whose names have been manually overridden to opt out of automatic device-name composition.
Phase 2: Frontend migration
With the backend API in place, the frontend replaces its string-stripping logic with direct consumption of the structured name components. The compute_entity_name.ts and strip_prefix_from_entity_name.ts files are refactored or removed. Frontend PR #30147 tracks this. All core cards, pickers, device pages, and settings panels use the new approach. The existing name composition controls (shipped in 2025.11) continue to work but are now backed by structured data rather than string heuristics.
Custom cards continue to receive friendly_name through the state object and are unaffected. No deprecation period for custom card compatibility is needed in this phase.
Phase 3: Companion app migration
iOS and Android companion apps adopt the registry-based naming model. This means querying the entity and device registries (which the apps may already partially do for other purposes) and implementing context-aware name composition for native surfaces. For example, a widget scoped to a specific device could show just the entity name; a notification could include the full composed name.
The apps should gracefully fall back to friendly_name when registry data is unavailable (e.g., older server versions). This phase depends on Phase 1 being complete and can run in parallel with Phase 2.
Community signals
Entity naming is one of the most persistently raised topics across the Home Assistant community.
Architecture discussions:
- architecture #1185: "Allow editing entity name instead of friendly name" (January 2025, substantial community input, no resolution)
- architecture #957: Entity naming for multi-channel devices (closed, solved via translation placeholders)
- architecture #909: Adjust naming scheme for translated names (accepted and implemented)
- architecture #1023: Allow
has_entity_name = False (closed; Frenck confirmed the property is transitional only)
Feature requests (GitHub Discussions):
- Discussions #16: "Make entity naming, device naming, and entity_id generation easier to manage and use" (June 2025, comprehensive proposal covering naming UX overhaul)
- Discussions #1157: "Shelly redundant naming of Entities" (device name duplication in entity names)
- Discussions #869: "Area Name on Tile Card" (resolved by 2025.11 name composition)
Community forum:
Community forum: naming strategy threads. A recurring pattern across the community is users asking each other how to name their devices and entities. These threads exist because the system does not handle naming context well enough on its own, forcing users to develop personal conventions. This is exactly the problem the entity naming migration was designed to solve, and the fact that these threads continue to appear is a signal that the job is not done yet.
Risks & open questions
- Architecture decision needed. Architecture discussion #1185 has been open since January 2025 with no formal resolution. The exact shape of the backend API (how structured name components are exposed, how user overrides interact with automatic composition) needs to be decided before implementation can proceed. This is the primary blocker.
- Custom card ecosystem impact. While
friendly_name is maintained for backward compatibility, any changes to how the frontend renders names in core cards could affect community expectations and lead to confusion about whether custom cards should also update. Clear communication and documentation will be needed.
- Companion app coordination. The iOS and Android apps are maintained by different teams (Nabu Casa for iOS, community-driven for Android). Aligning both on the same naming API consumption timeline requires coordination.
- User-renamed entities. Entities where the user has previously edited the
friendly_name need a migration path. The system must preserve the user's intent (their chosen display name) while transitioning to the new model. This is a known challenge flagged in architecture discussion #1185.
- Voice assistant compatibility. Voice assistants (both local and cloud-based) currently use
friendly_name for entity matching. Any changes to how names are composed must preserve or improve voice matching accuracy.
- Localization edge cases. The current string-stripping approach is English-centric (whitespace as separator). The new structured approach must work correctly for languages where name composition follows different rules (e.g., word order, particles, separator characters).
Appetite
Large. This is a cross-cutting effort spanning core backend, frontend, and two companion apps. The backend API and architecture decision (Phase 1) are the critical path. Phase 1 and Phase 2 together could reasonably target 2 cycles of focused work. Phase 3 (companion apps) is incremental and can follow at its own pace, likely adding 1 additional cycle.
Execution issues
Populated once a bet is approved.
Decision log
| Date |
Decision |
Outcome |
| March 16, 2026 |
Issue created to capture the remaining entity naming work as a betting table opportunity. |
Proposed |
Problem statement
In July 2022, Home Assistant introduced a new entity naming model (
has_entity_name) to separate device names from entity names, enabling context-aware display throughout the product. The core idea: entities carry only their own name (e.g., "Temperature"), the device name lives in the device registry (e.g., "Living Room Sensor"), and Home Assistant composes the appropriate display name depending on where it appears. On a device page, you see "Temperature." In an entity picker, you see "Living Room Sensor Temperature." On a dashboard card scoped to a specific area, you can omit the area entirely.The backend migration is largely complete. The majority of config-flow integrations have adopted
has_entity_name, and the number continues to grow. It is a Bronze-tier requirement in the Integration Quality Scale, mandatory for all new integrations with no exceptions. Entity name translations, translation placeholders for multi-channel devices, and device-class-based name fallback have all shipped.The frontend has started to deliver on the original vision. Entity pickers show device and area context (2025.5). Dashboard cards support name composition controls (2025.11). The target picker shows full hierarchical context (2025.11).
However, the architecture underneath is not finished. The frontend still computes display names by stripping the device name prefix from the pre-composed
friendly_nameattribute using fragile string heuristics (strip_prefix_from_entity_name.ts,compute_entity_name.ts). This approach is locale-unfriendly, breaks whenfriendly_namehas been manually overridden, and caused crashes in 2025.5 when entities had non-string names (frontend #25456, #25671). The companion apps (iOS and Android) rely entirely on thefriendly_namestate attribute for all native surfaces: widgets, watch complications, CarPlay, Control Center, entity pickers, and notifications. They do not query entity or device registries for structured name components and cannot do context-aware display.This matters for the "Make Home Assistant More Approachable" goal. Entity naming remains one of the most consistently raised pain points in the community. New users are confused by the relationship between
name,friendly_name,entity_id, and the registry. Device names get prepended to entity names creating absurd duplications. Dashboard cards show names that are too long and truncate on mobile. The 2022 vision of "the system just handles naming correctly based on context" is only partially delivered, and the remaining gaps are the ones users feel most acutely.Completing this migration is also a prerequisite for future work. The ability to edit
entity.namedirectly (instead of the composedfriendly_name) depends on the backend exposing structured name components. Context-aware voice assistant responses depend on it. Any future deprecation of thefriendly_nameattribute depends on all first-party consumers (frontend, companion apps) being migrated off it.Scope & Boundaries
In scope
friendly_namestring manipulation.compute_entity_name.tsandstrip_prefix_from_entity_name.ts. Frontend PR #30147 ("Simplify entity name computation," opened March 13, 2026, labeled "wait for backend") is the tracking PR for this work.entity.nameinstead offriendly_name. When a user "renames" an entity, they should be editing the entity's own name field, not the pre-composedfriendly_name. This enables the system to continue composing display names correctly after a rename. Architecture discussion #1185 covers this in detail.friendly_nameattribute remains available for backward compatibility but should no longer be the primary source of truth.friendly_name. Thefriendly_namestate attribute continues to be emitted for third-party consumers (custom cards, custom integrations, voice assistants, external tools). No deprecation offriendly_nameis in scope for this bet.Not in scope
has_entity_name. This is handled through normal Integration Quality Scale enforcement and is not blocked by this work.friendly_namestate attribute. That is a future step that depends on this work being complete.default_entity_id/object_iddeprecation (deadline 2026.4, tracked in core #157241 and related issues).entity_idis generated or updated on rename.Foreseen solution
The work breaks down into three phases that can be partially parallelized.
Phase 1: Backend structured name API
Extend the entity registry WebSocket API to expose the raw name components:
entity.name(the entity's own name, which may beNonefor primary entities),device.name, andarea.nameas discrete fields. This gives all consumers (frontend, companion apps, voice) the data they need to compose display names contextually. Thefriendly_namestate attribute continues to be computed and emitted as before for backward compatibility.This phase also includes adding the ability for users to edit the entity's own name (
entity.name) through the entity registry, separate from the composedfriendly_name. A flag (working name: "use as full name" or similar) allows entities whose names have been manually overridden to opt out of automatic device-name composition.Phase 2: Frontend migration
With the backend API in place, the frontend replaces its string-stripping logic with direct consumption of the structured name components. The
compute_entity_name.tsandstrip_prefix_from_entity_name.tsfiles are refactored or removed. Frontend PR #30147 tracks this. All core cards, pickers, device pages, and settings panels use the new approach. The existing name composition controls (shipped in 2025.11) continue to work but are now backed by structured data rather than string heuristics.Custom cards continue to receive
friendly_namethrough the state object and are unaffected. No deprecation period for custom card compatibility is needed in this phase.Phase 3: Companion app migration
iOS and Android companion apps adopt the registry-based naming model. This means querying the entity and device registries (which the apps may already partially do for other purposes) and implementing context-aware name composition for native surfaces. For example, a widget scoped to a specific device could show just the entity name; a notification could include the full composed name.
The apps should gracefully fall back to
friendly_namewhen registry data is unavailable (e.g., older server versions). This phase depends on Phase 1 being complete and can run in parallel with Phase 2.Community signals
Entity naming is one of the most persistently raised topics across the Home Assistant community.
Architecture discussions:
has_entity_name = False(closed; Frenck confirmed the property is transitional only)Feature requests (GitHub Discussions):
Community forum:
Community forum: naming strategy threads. A recurring pattern across the community is users asking each other how to name their devices and entities. These threads exist because the system does not handle naming context well enough on its own, forcing users to develop personal conventions. This is exactly the problem the entity naming migration was designed to solve, and the fact that these threads continue to appear is a signal that the job is not done yet.
friendly_name)Risks & open questions
friendly_nameis maintained for backward compatibility, any changes to how the frontend renders names in core cards could affect community expectations and lead to confusion about whether custom cards should also update. Clear communication and documentation will be needed.friendly_nameneed a migration path. The system must preserve the user's intent (their chosen display name) while transitioning to the new model. This is a known challenge flagged in architecture discussion #1185.friendly_namefor entity matching. Any changes to how names are composed must preserve or improve voice matching accuracy.Appetite
Large. This is a cross-cutting effort spanning core backend, frontend, and two companion apps. The backend API and architecture decision (Phase 1) are the critical path. Phase 1 and Phase 2 together could reasonably target 2 cycles of focused work. Phase 3 (companion apps) is incremental and can follow at its own pace, likely adding 1 additional cycle.
Execution issues
Populated once a bet is approved.
Decision log