Home Assistant Button Card: The Ultimate 2026 Guide to a Stunning UI

Updated on February 3, 2026

If you’re looking to completely revolutionize your Home Assistant user interface, the Home Assistant Button Card is, without a doubt, the definitive tool you need in 2026. This custom card lets you go far beyond standard buttons, offering a level of customization that can breathe new life into your Lovelace dashboards. In this updated guide, I’ll show you how to push its capabilities to the limit to create an interface that’s not just functional, but absolutely stunning.

Button Card’s Killer Features in 2026

The Button Card’s popularity is no accident. Its versatility comes from a powerful feature set that has been maintained and improved over the years:

1. Universal Entity Support: It works with virtually any Home Assistant entity, especially those with toggleable states (lights, switches, scripts, etc.).
2. Multi-Action Powerhouse: Lets you configure up to 6 different actions using tap, double-tap, and hold. Available actions include none, toggle, more-info, navigate, url, and call-service.
3. Extreme Visual Customization: Gives you total control over colors, icons, sizes, and raw CSS styles. The color can be fixed, automatic (based on a light’s color), or dynamic based on an entity’s state.
4. Dynamic States: You can define different icons, colors, and styles for each state of an entity (e.g., one icon for ‘on’, another for ‘off’, and a third for ‘unavailable’).
5. JavaScript Template Support: For next-level customization, it supports JS templates in most of its fields, allowing for complex conditional logic directly in your card’s configuration.
6. Flexible Layouts: It comes with multiple predefined layouts to organize the icon, name, and state, and even allows you to create your own custom layouts.
7. Built-in Animations: Supports native animations like blink and spin, perfect for indicating active or alert states.
8. Integrated Security: Includes confirmation dialogs before executing an action and a lock mechanism to prevent accidental presses on sensitive controls.
9. Haptic Feedback Integration: Natively supports haptic feedback for the Home Assistant companion app on both iOS and Android.

Easy Installation via HACS

In 2026, the easiest and most recommended way to install and maintain the Button Card is through HACS (Home Assistant Community Store). If you don’t have it installed yet, I highly recommend looking up a guide—it’s essential for any serious Home Assistant user.

Once HACS is up and running:

1. Navigate to HACS > Frontend.
2. Click the blue “Explore & Download Repositories” button.
3. Search for “Button Card” and select it.
4. Click “Download” and follow the instructions to add the resource to your Lovelace configuration.

Home Assistant Button Card: The Complete Configuration Guide

The card is configured entirely in YAML. Below, we’ll break down the most important options you’ll need to master it.

Core Configuration Options

These are the fundamental properties for defining your card’s behavior and appearance.

Defining Actions (tap, hold, double_tap)

Each of the three actions (tap_action, hold_action, double_tap_action) is an object containing an action property and, optionally, additional data. For example:

tap_action:
  action: call-service
  service: light.turn_on
  service_data:
    entity_id: light.kitchen
    brightness: 255

Action Confirmation

This is ideal for destructive or important actions, like shutting down a server or opening the garage door.

Security Lock

Displays a lock icon that must be pressed to “unlock” the button for a few seconds, allowing normal use.

Dynamic & Custom States

This is where the real magic of the Button Card happens. The state section lets you change the card’s appearance based on the entity’s state. The system evaluates the list of states in order and applies the first style that matches.

Comparison Operators

Practical Home Assistant Button Card Examples (2026)

Let’s see how to apply all of this with some real-world YAML examples you can copy and adapt for your own setup.

Example 1: Animated Fan with Custom Images

This one’s a classic. We’ll display a custom image of a fan that spins when it’s on. Your images should be placed in your /config/www/ folder.

type: custom:button-card
entity: fan.office_fan
show_entity_picture: true
tap_action:
  action: toggle
state:
  - value: 'off'
    entity_picture: /local/icon-fan-off.png
  - value: 'on'
    entity_picture: /local/icon-fan-on.png
    styles:
      entity_picture:
        - animation: 'rotating 1s linear infinite'

Example 2: Advanced RGB Light Control

This button controls a light. A single tap toggles it on or off. A long press opens the more-info dialog to change the color and brightness. The icon’s color will automatically reflect the actual color of the light.

type: custom:button-card
entity: light.living_room_led_strip
name: Living Room LED
icon: mdi:led-strip-variant
color_type: icon
color: auto
tap_action:
  action: toggle
hold_action:
  action: more-info
state:
  - value: 'off'
    styles:
      icon:
        - opacity: 0.5
  - value: 'on'
    styles:
      icon:
        - animation: 'blink 2s linear infinite'
        - filter: brightness(120%)

Example 3: Multi-Action Blinds/Cover Button

A button to control your blinds. A single tap toggles them open or closed, a double tap stops them mid-travel, and a long press opens the position slider.

type: custom:button-card
entity: cover.bedroom_blinds
name: Blinds
icon: mdi:blinds
tap_action:
  action: call-service
  service: cover.toggle
double_tap_action:
  action: call-service
  service: cover.stop_cover
hold_action:
  action: more-info
state:
  - value: 'open'
    icon: mdi:blinds-open
  - value: 'closed'
    icon: mdi:blinds

Example 4: Scene Activator with Confirmation

A simple button to trigger a scene, but with a confirmation dialog to prevent accidental activation.

type: custom:button-card
name: Movie Mode
icon: mdi:movie-open
tap_action:
  action: call-service
  service: scene.turn_on
  service_data:
    entity_id: scene.movie_mode
  confirmation:
    text: 'Are you sure you want to activate Movie Mode?'
styles:
  card:
    - background-color: '#333355'
    - color: white

Common Troubleshooting Steps

While Button Card is incredibly stable, you can occasionally run into issues. Here are the most common ones and how to fix them:

• Error: “Custom element doesn’t exist: button-card”: This is the number one problem people face. It means Home Assistant failed to load the card’s code.
  • Solution 1: Do a hard refresh and clear your browser’s cache completely.
  • Solution 2: Double-check that the resource path to the button-card.js file under Settings > Dashboards > Resources is correct. HACS should handle this automatically, but a manual check never hurts. The path should look like /hacsfiles/button-card/button-card.js.
• The card doesn’t show up or displays a YAML error:
  • Solution: This is almost always caused by an indentation error in your YAML code. Use an editor like the Studio Code Server add-on to validate your syntax before saving.
• A template isn’t working as expected:
  • Solution: JavaScript templates must be wrapped in triple brackets: [[[ ... ]]]. A common mistake is forgetting the brackets or using incorrect syntax. Test your logic in the Developer Tools > Template section of Home Assistant to debug your code before putting it in the card.

With this definitive 2026 guide, you have everything you need to take your Home Assistant automations and customizations to the next level with the Button Card. Now it’s time to start experimenting and build the dashboard of your dreams!