ESPHome: Redesign the main dashboard

[carlhye]

Problem statement

ESPHome's current dashboard becomes difficult to navigate in large deployments where users manage dozens or even hundreds of devices. Users struggle to quickly locate specific devices, compare device states across their fleet, and access relevant troubleshooting data at a glance. While the search function helps, it doesn't solve the core problem: there's no efficient way to view, sort, and compare multiple devices simultaneously.

Additionally, OHF's strategic direction requires tighter design alignment between ESPHome and Home Assistant to highlight their shared ecosystem. A proactive redesign now prevents technical debt and creates visual cohesion across the OHF product family.

This impacts users with large ESPHome deployments (10+ devices) who need operational visibility, as well as all users who benefit from improved UX consistency across the OHF ecosystem. Solving this matters because it reduces friction in device management workflows and strengthens the perceived integration between ESPHome and Home Assistant.

Scope & Boundaries

In scope

• Visual redesign of dashboard to align closer to Home Assistant's design language
• Card/tile view refresh (default view when users install):
  • Show device state (online, offline, draft, etc.)
  • Show update availability indicator
  • Quick access to logs
  • Modern card design with improved information hierarchy
• New list view for compact device management:
  • Sortable columns (click column header to sort)
  • Configurable columns (users choose which data to display)
  • Relevant data points as columns (name, IP, MAC, SSID, signal strength, online status, firmware version, etc. - final list determined with developer input based on data availability)
  • Multi-select checkboxes for bulk operations - options for bulk changes displayed in the header of the list view, when one or more devices are checked
• Bulk actions in list view: update selected, delete selected, etc.
• View toggle: Card/list view switcher using Material icons (grid_view for cards, list for list view)
• Settings menu (⠇ in top right):
  • Dark/light/auto theme mode
  • Secrets file editor/settings
  • Update all devices
  • Clean all (clear build cache)
• Persistence: Remember user's view preference (card vs list) and list column configuration across sessions

Not in scope

• Mobile-specific responsive design (desktop/tablet first)
• Advanced filtering beyond column sorting (e.g., saved filters, complex queries)
• Device grouping or tagging system
• Real-time status updates (keeping existing refresh mechanism)
• Dashboard customization/widgets (e.g., adding custom cards)
• Comprehensive onboarding flow for new design
• Migration of existing user preferences (fresh start for all users)
• Integration with Home Assistant's own device views

Foreseen solution

Overall Layout:

• Top bar with view toggle (grid_view / list icons) and settings menu (⠇)
• Search bar remains prominent
• Main content area adapts to selected view

Card View (Refreshed):

• Maintain familiar tile/grid layout
• Each card shows:
  • Device name & icon
  • Status badge (online/offline/draft) with color coding
  • Update available indicator (badge or icon)
  • Quick action buttons (logs, configure, etc.)
• Visual styling updated to match HA design patterns (colors, spacing, shadows, typography)

List View (New):

• Data table with fixed header
• Default columns: Name, Status, IP, Signal Strength, Last Seen, Actions
• Column header click to sort (ascending/descending with visual indicator)
• Column configuration button/menu to show/hide columns
• Multi-select checkboxes in leftmost column
• Bulk action bar appears when items selected (Update X devices, Delete X devices)
• Compact row height for high information density

Settings Menu (⠇):

• Theme selector (Dark / Light / Auto with system preference)
• "Secrets file" option → opens secrets editor
• "Update all devices" action
• "Clean all" → clear build cache for all devices

Persistence:

• Store view preference (card/list) in browser localStorage or user preferences
• Store list view column configuration in browser localStorage
• Restore on page load

Visual Design Alignment:

• Adopt HA's color palette, spacing system, and component styles
• Use Material Design icons consistently
• Match typography hierarchy
• Responsive breakpoints similar to HA

LINK to Figma file.

Community signals

A community member has already submitted a PR implementing a list view, demonstrating demand for this feature. This bet builds on that signal while ensuring comprehensive design alignment and additional functionality.

Link to PR: esphome/dashboard#756

Risks & open questions

• Design consistency: How strictly should we match HA's design system? Do we adopt their entire component library, or just visual language? Needs coordination with HA design team.
• Data availability: Which device data points are reliably available for list view columns? Need developer input to confirm what can be exposed (IP, MAC, SSID, signal strength, uptime, etc.).
• Performance: How does list view perform with 100+ devices? Do we need virtualization/pagination?
• Bulk action safety: Bulk update/delete should require confirmation. What's the UX for partial failures (5 of 10 devices failed to update)?
• Community PR: How do we incorporate the existing community list view PR? Do we build on it, or start fresh with broader design alignment?
• Column configuration: Should there be preset column layouts (Minimal, Standard, Detailed) or just free-form customization? Should columns be horizontally resizable?
• Settings menu scope: Are there other settings that should live in the ⠇ menu that we're missing?
• Mobile: While out of scope initially, how does list view degrade on mobile? Is card view the only mobile option?

Appetite

Large - roughly 2-3 cycles of focused work across frontend and design, depending on resource allocation

This is a substantial redesign touching the core dashboard experience. Requires:

• Design work (HA alignment, new list view patterns, card refresh)
• Frontend implementation (new list view component, table sorting, column config, bulk actions, settings menu)
• State management (persistence, bulk selection)
• Backend API work (if new data endpoints needed for list view columns)
• Testing across various device counts and configurations
• Community PR evaluation and potential integration

Execution issues

No response

Decision log

Date	Decision	Outcome