Add Matter network visualization in Matter panel and aim for a consistent graph experience across protocols

[mkerstner]

Problem statement

Home Assistant currently offers network map visualizations for example for Z-Wave and Bluetooth in their respective settings panel, but no equivalent yet exists for Matter. This is particularly notable because the HA Matter server app already includes a working visualization for Matter over Thread and Wi-Fi - but it is currently only accessible from within the Matter server app's own Web UI, not from the Matter panel in HA itself.

Beyond the missing Matter map, the existing visualizations across Z-Wave and Bluetooth were shaped largely by the graph ZHA had before. The current graph library also has known limitations. As a result, the network maps lack a consistent visual and interaction language, and may not be serving protocol-specific goals well.

Community signals

WTH — Consistent network topology UI across Z-Wave, Zigbee, and Matter (HA "What the heck?!" month, Dec 2024)
A dedicated WTH post explicitly called for reusing the same frontend UI elements for network topology maps across ZHA, Z-Wave JS, and Matter — proposing a shared building block that all three integrations could use. Noted that ZHA has a map, Z-Wave JS has one in its standalone UI but not natively in HA, and Matter has neither.
→ https://community.home-assistant.io/t/wth-not-use-the-same-ui-frontend-elements-to-visualize-mesh-networking-topology-for-wireless-mesh-network-devices-in-native-zigbee-zha-z-wave-and-matter-integrations/803155

"Lost in dark Matter without a network diagram" (community.home-assistant.io, Jan 2026)
A user who had successfully set up Matter over Thread with a ZBT-2 expected to find a network diagram in the HA Matter panel and found none. The community response confirmed the visualization exists but requires manually enabling ports in the OTBR add-on and visiting a separate web interface
→ https://community.home-assistant.io/t/lost-in-dark-matter-without-a-network-diagram/972255

GitHub discussion — Thread network diagnostic map (home-assistant org, active through Sep 2025)
Mirrors the forum request at the GitHub org level. Community members noted the Matter server beta's Thread viewer is "awesome" but flagged that it uses hardware IDs rather than HA device names, and requested an additional tabular view alongside the graph.
→ https://github.com/orgs/home-assistant/discussions/584

Matter server migration FAQ (home-assistant/addons, 2025–2026)
The official migration notes for the new Matter Server explicitly describe the network visualizations for Thread and Wi-Fi as a significant addition to the server's Web UI, confirming the feature exists and is intentional but remains scoped to that app rather than the HA panel.
→ https://github.com/home-assistant/addons/blob/master/matter_server/MIGRATION_FAQ.md

User confusion about the visualization gap (community.home-assistant.io, Feb & Jun 2026)
Active threads show users discovering the Matter server visualization for the first time and struggling to interpret it (missing legend for dashed lines, unknown devices). The friction of accessing it via a separate app rather than the Matter panel is a recurring theme.
→ https://community.home-assistant.io/t/understanding-has-matter-server-network-mesh/981648
→ https://community.home-assistant.io/t/interpreting-the-matter-server-thread-network-mesh-visualisation/1013712

Scope & Boundaries

In scope

• Investigate what is preventing the Matter server app's existing visualization from being surfaced directly in the HA Matter panel, and whether those limitations can be resolved
• Evaluate what protocol data the existing Matter visualization exposes and whether it covers the meaningful cases (e.g. Thread mesh topology, parent-child relationships, link quality, ICD status)
• Investigate the feasibility of a shared visualization foundation across Matter, Z-Wave, and Bluetooth network maps
• Assess whether the current graph library is sufficient or whether an alternative would better serve protocol goals and a consistent design language
• If a shared approach proves too complex for a single cycle: surface the existing Matter visualization in the HA Matter panel as a standalone step, and defer the consistency work to a follow-on opportunity

Not in scope

• Building a Matter network visualization from scratch
• Redesigning the Z-Wave or Bluetooth maps as part of this opportunity (unless the shared-foundation path is chosen)
• Changes to how Matter / Thread data is collected or surfaced by the integration itself

Foreseen solution

The existing visualization in the Matter server app's Web UI is the starting point. Rather than building from scratch, the goal is to understand what it would take to bring that visualization into the HA Matter panel directly, and — where feasible — use it as the foundation for a more consistent graph experience across protocols.

Path A — Shared visualization foundation (preferred if feasible)
Resolve the limitations preventing the Matter server visualization from appearing in the HA Matter panel. Use that work as an opportunity to establish a common graph component or design pattern that all network maps in HA can build on. Align Z-Wave and Bluetooth maps to the same pattern within the same cycle if scope allows.

Path B — Matter map first, consistency later (fallback)
If the shared-foundation work is assessed as too intensive for a single cycle, focus solely on surfacing the existing Matter server visualization in the HA Matter panel. Capture learnings and use them to inform a dedicated consistency effort in a follow-on cycle.

The cycle starts with a scoping spike to identify the current limitations and determine which path is viable before committing to implementation.

Risks & open questions

• What are the specific technical limitations preventing the Matter server app visualization from being shown in the HA Matter panel, and are they resolvable within a reasonable scope?
• Is the current graph library capable of meeting the needs of all three protocols, or does switching libraries create migration risk for existing maps?
• How much of the existing Z-Wave and Bluetooth map code is reusable versus needing a full redesign to align with a shared foundation?
• ICD devices (battery-powered, intermittently connected) may not report topology data reliably — how should the map handle absent or stale nodes in the future?

Appetite

Medium - 3-4 weeks

Execution issues

No response

Decision log

Date	Decision	Outcome

[MindFreeze]

On the frontend we can easily render a graph with the same reusable code for the existing protocol graphs. If we want a different design or some new fancy functionality, it would be more work, but that can be deferred to later.
What is missing is the data from the Matter server through Core.

• Nodes with their ID and type
• Connections between nodes with type and potentially strength
• Update mechanism. Is the data updated based on some event subscription or simple polling?

[mkerstner]

CC: @Apollon77 from Matter server perspective

[Hedda]

Home Assistant currently offers network map visualizations for example for Z-Wave and Bluetooth, but no equivalent exists in the Matter panel.

Don't forget about using ZHA (Zigbee) for reference, it was even the first integration to have network map visualization for mesh networking!

• https://www.home-assistant.io/integrations/zha#visualization-of-the-zigbee-network-topology-and-device-links

On the frontend we can easily render a graph with the same reusable code for the existing protocol graphs. If we want a different design or some new fancy functionality, it would be more work, but that can be deferred to later.

IMHO having full consistency / coherence for settings and configuration UI layout and flows between interface for Matter. ZHA (Zigbee), Z-Wave, and Bluetooth for overall coherant settings and configuration will be key to shorten the learning-curve for new users and beginners.

• Further shape our coherent device and protocol support goals#15

This opportunity indirectly also continues to lay extended foundation for unifying the UX and UI across all supported protocols for end-users:

• Unify setup experience across all supported protocols goals#14

as well as help make Home Assistant more approachable too to reduce early-use friction by having the same UI and UX for all protocols:

• Make Home Assistant More Approachable goals#7

That is, having similar features look and feel the same across all supported protocols will make it easier to find and understand config/data.

• Shape the UI around how people in a household find, use, and share their smart home information #129

Indirectly this can also help strengthen Home Assistant's ecosystem when promoting the WWHA program to future potential partners:

• Strengthen Home Assistant Ecosystem goals#2