Give the companion app platform-standard navigation (Modal presentations and top navigation bar) #249

Problem statement

Follow-up to #244, narrowed from tab-bar navigation to the two surfaces users touch most often: modal presentation (entity more-info and other dialogs) and the top navigation bar of those presentations.

The frontend's dialogs are good, and the more-info dialog in particular is well designed and consistent across every client. This opportunity does not change what they show or how they work. It changes how the companion app presents them: as native sheets with a native navigation bar, so that opening an entity in Home Assistant feels the same as opening a detail screen in Apple Home, Messages, Mail or Maps, the apps a household member switches to and from several times a day.

What native presentation brings

• Perceived app quality. A sheet that slides in with the system's motion, materials and detents, with the title, back/close and actions exactly where iOS puts them in every other app, reads instantly as a first-class app. This is the layer where the "feels like a web wrapper" perception is formed, and where it can be removed without touching a single dashboard or dialog.
• Conformance to the Human Interface Guidelines by construction. Using the system containers means the app follows Apple's navigation patterns, accessibility behaviour and design language automatically, rather than us approximating them and re-checking every release.
• Future-proof to Apple's changes. Apple regularly redesigns bars and sheets (Liquid Glass in iOS 26 being the latest). Apps built on system containers pick the new look and behaviour up the day the OS ships; hand-drawn chrome always lands one release behind and consumes a cycle to catch up.
• Free adaptation to new form factors. With iOS 27 and iPhone Duo, Apple moves navigation controls to a vertical side layout on the wide display and presents them as a sidebar on the inner display. Only bars and sheets provided by system containers participate in this; custom or web-rendered bars are explicitly excluded. Native presentation gives us these adaptations, and whatever comes after, with no additional work.

Who is impacted: every iOS/iPadOS user of the companion app, and especially the non-technical household members for whom the app is the primary (often only) interface to Home Assistant. Entity more-info is the most frequently opened screen in the app, so its presentation shapes the impression of the whole product.

Why it matters to OHF: the companion apps are how most people experience Home Assistant on their phone. Native presentation raises the perceived quality of the product, supports adoption by less technical household members, protects App Store ratings, and has been requested by iOS users for years. It does this while leaving the frontend team fully in control of dialog content and behaviour.

Compared to #244 this opportunity is smaller and less controversial: no decisions about dashboards or tabs, no change to dialog content, and the approach is already proven by two working draft PRs. It also lays the frontend ↔ app contract that a later tab-bar effort would reuse.

Community signals

Proof of concept (working draft PRs)

• iOS: Add frontend native modal presentation communication and UI home-assistant/iOS#5856 — "Add frontend native modal presentation communication and UI". Presents frontend routes in a native sheet with a second web view, app-controlled navigation bar, detents, stacked modals, modal reuse for performance. Shipped behind an App Labs flag ("Native entity details", iOS 26+). Includes screenshots and demos on iPhone and iPad.
• Frontend: Add companion apps native modal presentation communication home-assistant/frontend#54260 — "Add companion apps native modal presentation communication". modal/open, modal/update, modal/action, modal/close messages, a frameless /modal route, opt-in NATIVE_MODAL_DIALOGS registry, fully backward compatible for dialogs that are not listed.

Community demand

• Long-standing, recurring requests from iOS users across the community forum, Discord, GitHub issues and App Store reviews for the app to "feel native": native sheets for entity details, a proper navigation bar, drag-to-dismiss, and system look and feel. Summarised in Give the companion app platform-standard navigation #244 ("feels like a web wrapper", "What the heck?!" navigation comments, HACS workarounds that exist only to make chrome feel native). The signal is strongest on the Apple side.
• The discussion on Give the companion app platform-standard navigation #244 showed multiple iOS developers volunteering to prototype, and general sentiment described there as "hungry and frustrated".

Platform direction

• Apple HIG — Sheets and Navigation bars: sheets with detents and a system navigation bar are the standard way to present focused, secondary content on iPhone. https://developer.apple.com/design/human-interface-guidelines/sheets · https://developer.apple.com/design/human-interface-guidelines/navigation-bars
• iOS 26 Liquid Glass redesign of bars and sheets; iOS 27 / iPhone Duo adaptations (https://developer.apple.com/videos/play/tech-talks/111462/). Only system containers pick these up; web-rendered chrome is left behind on every release.
• Apple Home, Google Home, Messages, Mail, Maps, WhatsApp, Telegram, Outlook all present detail views as native sheets with a system bar. These are the apps a household member switches to and from several times a day; they set the expectation the companion app is measured against.

Scope & Boundaries

In scope

• A versioned frontend ↔ companion-app contract for native modal presentation: open, update (title, breadcrumb, toolbar actions, layout/detent hints), action, navigate, close.
• A frontend /modal route that renders a dialog frameless, plus an opt-in registry so dialogs can be made native-modal eligible one by one without affecting the browser/PWA experience.
• iOS/iPadOS implementation: native sheet with detents, app-drawn top navigation bar (title, back/close, toolbar actions supplied by the frontend), stacked modals, reuse/pre-warming for fast presentation, correct behaviour with keyboard, safe areas, Dynamic Type and VoiceOver.
• Entity more-info as the first and primary dialog; follow with the most-used dialogs (e.g. entity settings, history, related, Assist) as the contract proves out.
• Ship behind App Labs first, then default on for iOS 26+ once quality is validated; classic web dialogs remain the fallback.
• Documentation for frontend contributors on how to make a dialog native-modal eligible, and for Android on how to adopt the same contract.

Not in scope

• Bottom tab bar / sidebar navigation of dashboards (remains Give the companion app platform-standard navigation #244).
• Rewriting dialog content in native code: dialog bodies stay frontend-rendered; only presentation and the bar become native.
• Android implementation (the contract is platform-neutral and Android should follow, but is not part of this bet).
• Changes to the browser/PWA experience — unlisted dialogs and non-companion clients keep working exactly as today.
• Core API changes.
• macOS Catalyst, which does not support sheets in the same way.

Foreseen solution

The frontend stays the source of truth for what is shown; the app owns how it is presented. This is what the two draft PRs implement:

1. Contract (frontend#54260). When a native-modal-eligible dialog is requested and the host app advertises support, the frontend sends modal/open with the route, title and breadcrumb instead of rendering the dialog inline. While the modal is alive it sends modal/update for header and layout changes (title, toolbar buttons, detent hints), receives modal/action when the user taps a toolbar item, and sends modal/close when done. Dialogs opt in by registering in NATIVE_MODAL_DIALOGS, accepting standalone / withoutHeader, and using JSON-serialisable params; they can optionally implement performHeaderAction(id) for custom bar buttons. Nested dialogs stack as separate native modals.

2. iOS presentation (iOS#5856). The app presents a sheet (UISheetPresentationController with frontend-specified detents) hosting a second web view in a nativeModal role that loads the frameless /modal route. The app draws the navigation bar natively from the modal/update payload, so back/close, title and actions follow the HIG and pick up Liquid Glass and future system styling automatically. Stacked modals dismiss as a stack; the modal web view is reused after dismissal and pre-warmed once the main frontend has loaded so the first open is instant. Exposed as the App Labs feature "Native entity details" on iOS 26+.

3. Rollout. Start with entity more-info (highest-traffic dialog), gather feedback through App Labs, extend the registry to further dialogs, then enable by default on iOS 26+. Any dialog not in the registry, any older iOS version, and every non-companion client keep the existing web dialogs, so there is no big-bang risk.

4. Reuse. The same contract is what a future bottom-tab or sidebar effort (Give the companion app platform-standard navigation #244) and the Android app would build on, so this is the first step of platform-standard navigation rather than a one-off.

Risks & open questions

• Memory and performance of a second web view. Hosting the modal in its own web view costs memory and a cold start. The PoC mitigates with reuse and pre-warming; needs measurement on older/low-end devices and with several stacked modals before default-on.
• State parity with the inline dialog. Dialog params must be JSON-serialisable and the modal web view must have the same auth/connection state as the main one. Edge cases: connection loss while a modal is open, deep links that open a dialog directly, dialogs that open other dialogs or navigate the main view (modal/navigate).
• Which dialogs qualify. Not every dialog benefits from a sheet; some are tiny confirmations. Need a simple rule for what goes in NATIVE_MODAL_DIALOGS so frontend contributors don't have to guess, and a review path so the registry stays intentional.
• Two behaviours to maintain. Until default-on, web and native dialog presentation coexist; the frontend must not diverge (e.g. a header action that exists only in one). Plan: the frontend dialog remains the single implementation, native mode only changes the frame and header.
• Theming expectations. The community themes every pixel of the frontend; the native bar is platform-owned and will not follow custom themes beyond accent/dark mode. State this boundary clearly in the release blog, with the browser/PWA as the fully themeable alternative.
• iOS 26+ only. Older iOS versions keep web dialogs, so a share of users won't see the change initially. Acceptable given the adoption curve of iOS releases; confirm the minimum version choice.
• Android follow-up. If Android does not adopt the contract, the two apps diverge in dialog presentation. Mitigation: contract is platform-neutral and documented; Android tracked as its own opportunity.
• Catalyst/macOS is excluded because it lacks comparable sheet presentation; confirm this is acceptable for the Mac app.

Appetite

Medium — roughly one cycle across frontend and iOS. The frontend contract and the iOS presentation already exist as working draft PRs (frontend#54260, iOS#5856); the remaining work is review, hardening (performance, edge cases, accessibility), extending the dialog registry beyond more-info, App Labs feedback and the default-on rollout. Android adoption of the contract is a separate, later bet.

Execution issues

Proof-of-concept PRs (draft):

• Add frontend native modal presentation communication and UI home-assistant/iOS#5856
• Add companion apps native modal presentation communication home-assistant/frontend#54260

Tracking issues to be added once approved.

Decision log