Device Card

A comprehensive card to display and organize your Home Assistant device entities

Built with the tools and technologies:

Table of Contents

• Overview
  • Device Card
  • Integration Card
• Features
  • Device Information Display
  • Problem Detection
  • Entity Pictures
  • Expandable Sections
  • Entity Attributes
  • Pinned Entity State
  • Percent Gauges
  • Collapsible Card
  • Compact Mode
  • Advanced Sorting
  • Pattern Matching
  • Entity Interactions
  • Visual Styling
• Installation
• Usage
• Configuration Options
• Example Configurations
• Project Roadmap
• Contributing
• License
• Acknowledgments
• Code Quality
• Build Status

Overview

Device Card

A custom card for Home Assistant that provides a comprehensive overview of any device in your system. The card organizes device information into expandable sections, displaying sensors, controls, configuration options, and diagnostic data in a clean, user-friendly interface.

Integration Card

The Integration Card automatically finds and displays all devices from a selected integration domain. This is useful for:

• Viewing all your lights, sensors, or switches from a specific brand or system
• Creating dedicated dashboards for specific systems in your home
• Monitoring the status of all devices in an integration at once

Features

Device Information Display

• Shows device name and model information
• Organizes entities into logical categories:
  • Controls - for interactive elements like buttons and switches
  • Sensors - for data readings and status information
  • Configuration - for device settings
  • Diagnostic - for troubleshooting information

Problem Detection

• Automatically detects entities labeled as "problem" in the device based on their device_class
• Visual indication when problems are detected (card border turns red)
• Easy identification of issues requiring attention
• Problem entities show a green or red indicator to their left

Entity Pictures

With an optional flag, you can showcase entity pictures when available. There must exist an entity with an entity_picture attribute.

Expandable Sections

• Collapsible sections for better organization of information
• Preview counts for sensors to reduce visual clutter
• Ability to expand sections to see all entities

Entity Attributes

• Click an entity to expand it and show it's attributes
• This behavior can be disabled by setting tap_action to "none"

Pinned Entity State

Display a specific entity's state prominently in the card header, providing instant visibility for your most important information. Perfect for temperature sensors, battery levels, or any critical value you want to monitor at a glance.

Percent Gauges

Visual percentage indicators for entities with percentage values. Gauges automatically change color based on the value (red for low, yellow for medium, green for high), making it easy to visually assess battery levels, sensor readings, and more.

Collapsible Card

Cards can be configured to start in a collapsed state, allowing you to keep dashboards clean while still having quick access to detailed information when needed. Simply click the header to expand and reveal all sections.

Compact Mode

A space-efficient layout option that reduces padding and margins, allowing you to fit more information in the same space. Ideal for information-dense dashboards or smaller screens.

Advanced Sorting

Customize how entities are sorted within each section. Sort by domain, entity ID, name, or state value in either ascending or descending order. This makes it easier to prioritize the most relevant information for your needs.

Pattern Matching

Use wildcards and regular expressions in your entity and device exclusion patterns. This powerful feature allows for more flexible configuration, making it easy to include or exclude groups of entities based on naming patterns.

Entity Interactions

• Configure custom actions for tap, hold, and double tap interactions
• Actions include navigating to other views, calling services, or opening more-info dialogs
• Setting a tap_action disables the entity attribute expansion behavior
• Actions can be configured in both YAML and the visual editor

Visual Styling

• Consistent with Home Assistant design language
• Responsive layout that works on both desktop and mobile
• Clear visual hierarchy for easy reading

Installation

HACS (Recommended)

1. Open HACS in your Home Assistant instance
2. Click the menu icon in the top right and select "Custom repositories"
3. Add this repository URL and select "Dashboard" as the category
   • https://github.com/homeassistant-extras/device-card
4. Click "Install"

Manual Installation

1. Download the device-card.js file from the latest release in the Releases tab.
2. Copy it to your www/community/device-card/ folder
3. Add the following to your configuration.yaml (or add as a resource in dashboards menu)

lovelace:
  resources:
    - url: /local/community/device-card/device-card.js
      type: module

Usage

Add the card to your dashboard using the UI editor or YAML:

Card Editor

Caution

The editor may delete advanced settings, such as regex or wildcards. Make a copy of the card config prior to using the UI editor.

The card is fully configurable in the UI editor. Simply select "Custom: Device Card" when adding a new card to your dashboard, then select your device from the dropdown.

You can also add the integration card via the UI editor. It will accept mostly the same configuration as the device card.

YAML

This is the most minimal configuration needed to get started on the device card:

type: custom:device-card
device_id: YOUR_DEVICE_ID

The card will automatically:

• Display the device name and model information
• Organize all entities related to the device into appropriate sections
• Show collapsible sections for Controls, Configuration, Sensors, and Diagnostics
• Highlight any detected problems

This is the most minimal configuration needed for the integration card:

type: custom:integration-card
integration: zwave_js

The card will automatically:

• Display a device card for each device in the integration

Configuration Options

Device Card

Name	Type	Default	Description
device_id	string	Required	The Home Assistant device ID for your device
title	string	Device name	Optional custom title for the card
preview_count	number	All items	Number of items to preview before showing "Show More" button
exclude_sections	list	none	Sections of entities to exclude. See below.
exclude_entities	list	none	Entities to remove from the card.
section_order	list	none	Custom order for displaying sections. See below.
sort	object	See below	Sort options for entities
features	list	See below	Optional flags to toggle different features
tap_action	object	none	Action to perform when tapping the card
hold_action	object	none	Action to perform when holding the card
double_tap_action	object	none	Action when double-tapping the card

Feature Options

Name	Type	Description
entity_picture	flag	Show entity picture when available
hide_device_model	flag	Hides the device model information
hide_title	flag	Hides the device card title
compact	flag	Uses compact layout with reduced spacing
collapse	flag	Initially displays the card collapsed

Sorting Options

Here's the markdown table for the sorting feature:

Option	Type	Default	Description
type	string	Required	Sorting method: domain, entity_id, name, or state
direction	string	asc	Sort direction: asc (ascending) or desc (descending)

Section Options

The following section names can be used with both exclude_sections and section_order:

• controls
• configurations
• sensors
• diagnostics

For section_order, the default order is: Controls, Configuration, Sensors, Diagnostic. Any sections not specified in your custom order will be displayed after the specified ones.

Integration Card

Most configuration options from the Device Card are supported:

Name	Type	Default	Description
integration	string	Required	The Home Assistant integration domain (e.g., zwave_js, hue)
title	string	Device name	Optional custom title for the card
hide_integration_title	boolean	False	Optional flag to hide the integration card title.
preview_count	number	All items	Number of items to preview before showing "Show More" button
columns	number	responsive	Fix the number of columns for device cards (1-6)
include_devices	list	none	Include only specific devices for the integration
exclude_devices	list	none	Specific devices to exclude from the integration display
exclude_sections	list	none	Sections of entities to exclude. See below.
section_order	list	none	Custom order for displaying sections. See below.
features	list	See above	Optional flags to toggle different features
tap_action	object	none	Action to perform when tapping the card
hold_action	object	none	Action to perform when holding the card
double_tap_action	object	none	Action when double-tapping the card

Note - include_devices, exclude_devices and exclude_entities accepts wildcards (*) and Regex

Example Configurations

Device Card

Basic Configuration

type: custom:device-card
device_id: 1a2b3c4d5e6f7g8h9i0j

Custom Title and Preview Count

type: custom:device-card
device_id: 1a2b3c4d5e6f7g8h9i0j
title: Living Room Thermostat
preview_count: 3

With Entity Picture

type: custom:device-card
device_id: 1a2b3c4d5e6f7g8h9i0j
features:
  - entity_picture

With Pinned Entity State

type: custom:device-card
device_id: 1a2b3c4d5e6f7g8h9i0j
entity_id: sensor.octoprint_print_progress

With Collapsed as Default

type: custom:device-card
device_id: 1a2b3c4d5e6f7g8h9i0j
features:
  - collapse

Excluding some entities and sections

type: custom:device-card
device_id: 1a2b3c4d5e6f7g8h9i0j
exclude_sections:
  - controls
  - configurations
  - diagnostics
exclude_entities:
  - update.home_assistant_core_update # Exclude by id
  - '*_uptime' # Exclude all uptime sensors
  - sensor.esp_* # Exclude all ESP sensors
  - /.*_(wired|wireless)/ # Regex match ending in wired or wireless

Custom section order

type: custom:device-card
device_id: 1a2b3c4d5e6f7g8h9i0j
section_order:
  - sensors # Show sensors first
  - controls
  - configurations
  - diagnostics

With custom actions

type: custom:device-card
device_id: 1a2b3c4d5e6f7g8h9i0j
tap_action:
  action: more-info
hold_action:
  action: call-service
  service: light.turn_on
  service_data:
    entity_id: light.living_room
double_tap_action:
  action: navigate
  navigation_path: /lovelace/0

With compact layout

type: custom:device-card
device_id: 1a2b3c4d5e6f7g8h9i0j
features:
  - compact

With custom action

Set hold action as more-info to keep attribute exansion for tap_action

type: custom:device-card
device_id: 1a2b3c4d5e6f7g8h9i0j
hold_action:
  action: more-info

With sort configuration

type: custom:device-card
device_id: 1a2b3c4d5e6f7g8h9i0j
sort:
  type: name
  direction: asc

Integration Card

Basic Configuration

type: custom:integration-card
integration: zwave_js

Custom Title and Compact Layout

type: custom:integration-card
integration: hue
title: Philips Hue Devices
features:
  - compact
  - hide_device_model

Excluding Sections

type: custom:integration-card
integration: matter
title: Matter Devices
exclude_sections:
  - diagnostics
  - configurations

Custom Actions for All Device Cards

type: custom:integration-card
integration: esphome
tap_action:
  action: more-info
hold_action:
  action: navigate
  navigation_path: /config/devices

Basic Configuration with Excluded Devices

You can use wildcard patterns with * to include, exclude devices or entities:

type: custom:integration-card
integration: zwave_js
exclude_devices:
  - b30c9bb17b44450d99ed41c6167e5c92 # Z-Wave Hub
  - 99f45623df8146e8a446f17e92d38272 # Guest Room Switch
  - esp_*_airfresh # Exclude all ESP air fresh devices
  - nous* # Exclude all devices starting with "nous"
  - /.*([Ss]upervisor)/ # Exclude devices ending in supervisor

In this example we would include only device_1

type: custom:integration-card
integration: zwave_js
include_devices:
  - device_1
  - device_2
  - device_3
exclude_devices:
  - device_2
  - device_3
  - device_4

In this example we would include only these 2 devices

type: custom:integration-card
integration: zwave_js
include_devices:
  - device_1
  - device_2

Project Roadmap

• Initial design: Create initial card design
• Enhanced customization: Add more customization options
• Custom section order and exclusions: Set the order in which sections are displayed & exclude things - thanks @andrewjswan
• Entity interactions: Configure tap, hold, and double-tap actions - thanks @andrewjswan
• Status badges: Quick status badges for device state
• Entity filtering: Filter specific entities from display - thanks @andrewjswan
• Integration Card: Rollup to see all devices - thanks @andrewjswan
• Hide device model: Option to hide device model information - thanks @andrewjswan
• Compact layout: Space-efficient layout option - thanks @andrewjswan
• Column control: Ability to define column count for integration card - thanks @andrewjswan
• Device exclusion: Ability to exclude devices from integration card - thanks @andrewjswan
• Wildcard/regex filtering: Exclude devices/entities by wildcard or regex patterns - thanks @andrewjswan
• Device inclusion: Include only specific devices option - thanks @andrewjswan
• Entity sorting: Add ability to sort entities - thanks @andrewjswan
• Card expansion: Ability to expand/collapse the device card - thanks @fgamache1
• Pinned entity state: Add pinned state entity display - thanks @fgamache1
• Integration title control: Modify/hide integration card title - thanks @andrewjswan
• Hide title feature: Device card can remove title
• Section exclusion: Add ability to exclude sections - thanks u/ctallc

Contributing

• 💬 Join the Discussions: Share your insights, provide feedback, or ask questions.
• 🐛 Report Issues: Submit bugs found or log feature requests for the device-card project.
• 💡 Submit Pull Requests: Review open PRs, and submit your own PRs.
• 📣 Check out discord: Need further help, have ideas, want to chat?
• 🃏 Check out my other cards! Maybe you have an integration that I made cards for.

Contributing Guidelines

1. Fork the Repository: Start by forking the project repository to your github account.
2. Clone Locally: Clone the forked repository to your local machine using a git client.

   git clone https://github.com/homeassistant-extras/device-card

3. Create a New Branch: Always work on a new branch, giving it a descriptive name.

   git checkout -b new-feature-x

4. Make Your Changes: Develop and test your changes locally.
5. Commit Your Changes: Commit with a clear message describing your updates.

   git commit -m 'Implemented new feature x.'

6. Push to github: Push the changes to your forked repository.

   git push origin new-feature-x

7. Submit a Pull Request: Create a PR against the original project repository. Clearly describe the changes and their motivations.
8. Review: Once your PR is reviewed and approved, it will be merged into the main branch. Congratulations on your contribution!

License

This project is protected under the MIT License. For more details, refer to the LICENSE file.

Acknowledgments

• Built using LitElement
• Inspired by Home Assistant's chip design
• Thanks to all contributors!

Code Quality

Forgive me and my badges..

Stats

Ratings

Build Status

Main

Release

Other