Button Card: Buttons That Look and Behave Exactly As Advertised

Mushroom gave you readable tiles and the "Office Now" card. Now it's time for the buttons the household actually taps every day, the status LED, the evening scene, and an LED signal test for the admin. You're installing Button Card from HACS and configuring tap and hold exactly the way you set them up back in Module 13.

Button Card gives you more control than Mushroom Entity, its own icon, color, size, separate styling per state, separate actions for tap and hold. It doesn't change automation logic. It doesn't add new entities. It's just a better way of triggering what you already have.

Plan on roughly forty minutes. You need HACS from Module 6 and Start Pro from Lessons 2 and 3. Plan for three buttons, two on Start, the LED and the scene, and one on Diagnostics, the script on hold.

Installing Button Card from HACS

Search HACS for Button Card under the Dashboard category. The GitHub project is custom-cards/button-card, by RomRider. After downloading, refresh Home Assistant's page. The YAML type is custom:button-card. Mushroom stays for Entity and Template. Reach for Button Card when the button's look matters, or when you need to separate tap, hold, and optionally double_tap.

Button Card is genuinely one of the oldest and richest custom cards in the HA ecosystem, with extensive documentation on RomRider's GitHub. This module uses its basics, entity, name, icon, tap_action, hold_action, show_state, and optionally styles and confirmation. Custom fields, animations, and multiple states are a topic for after the course, or for Lesson 8 with Card Mod.

Don't install fifteen cards at once. This lesson is one HACS integration and three buttons. A custom card doesn't fix a bad dashboard. A custom card improves a good one.

Button Card doesn't replace Mushroom

Mushroom stays for informational tiles, temperature, humidity, a plain entity state, the "Office Now" card. Reach for Button Card when a button needs a specific action, a bigger size, a separate tap, a separate hold, or a confirmation dialog. Don't convert all of Start Pro to Button Card just because it offers more options.

A simple choosing rule, information goes to Mushroom, a controlled action goes to Button Card, and diagnostics is often best left as plain entities.

A minimum, standard, and extended version

The minimum version puts the LED and the scene on Start as Button Cards, tap only, no hold. The standard version adds the test script as a Button Card on Diagnostics, hold only, with a confirmation dialog. The extended version adds simple state-based styling, an icon color that shifts between on and off, without animation or elaborate CSS.

Tap, hold, and double_tap

Button Card handles three gestures independently. tap_action is a short click, toggling the LED, activating the evening scene. hold_action is a press-and-hold, running script.office_led_signal on Diagnostics. double_tap_action is a double-click, this course doesn't use it on Start, but it's worth knowing it exists, say if you ever want double-tap for more-info and a plain tap for toggling.

Module 13's rule stands, only tap for everyday actions on Start and the mobile view. Hold on the diagnostic script belongs exclusively to Diagnostics or Admin. Don't combine both gestures on the evening scene's button, your partner shouldn't hold the scene button and accidentally trigger an LED test.

If hold fires on a short tap, set tap_action: none on the script's button and keep only hold. That's the pattern in the YAML sketch below.

Confirmation for risky actions

Actions that break something or annoy the household should genuinely require confirmation. In Module 13, restarting Home Assistant carried an extra safeguard on Admin. In Module 15, the LED test script on Diagnostics is worth protecting the same way, hold plus a dialog reading something like "Really run the signal test?"

In Button Card you add a confirmation block inside hold_action. The user holds the button, sees a dialog, and only then does the script run. Tap on the LED and the evening scene don't need confirmation, those are everyday, reversible actions.

Restarting Home Assistant never gets a Button Card on Start, even with confirmation attached. It stays in the Service section on Admin from Module 13.

Visual states: colors tied to the entity

Button Card lets you define appearance based on entity state through a state section or templates inside styles. The LED on could carry an amber background, off a gray one. A scene could briefly change its icon after activating. At this point in the course, show_state: true and a sensible icon are genuinely enough. Add conditional styling only once tap is working correctly.

An optional sketch for a state-driven background reads a state list with a value of "on" giving a warm amber-tinted card background, and a value of "off" giving a muted slate-tinted one.

You don't need to paste this in right away. Get the tap toggle working correctly first, then handle the cosmetics. Lesson 8's Card Mod will tie the styling together with the rest of the dashboard.

Tap and hold: Module 13's rules, carried forward

Module 13 established the split for actions. Module 15 cements it inside Button Card. Tap is an everyday household action, toggling the LED, activating the evening scene. Hold is a deliberate, slower action, script.office_led_signal only on Diagnostics or Admin. And never tap, restarting Home Assistant, reloading YAML, or clearing history.

The scene.office_test scene stays on Diagnostics or Admin, never on Start or the mobile view. Only scene.office_evening goes on Start.

Button 1: the status LED (tap toggle)

The switch.led_status_office entity, card name "Status LED." Tap toggles the state. You can leave hold empty or set it to more-info, never the diagnostic script. The LED signal script never lands on Start.

A standard-version sketch reads type: custom:button-card, entity: switch.led_status_office, name: Status LED, icon: mdi:led-on, show_state: true, a tap_action of toggle, a hold_action of more-info, some basic card styling for rounded corners and padding, a bolder name weight, and a slightly larger icon, plus state-based icon colors, a warm tone for on, the theme's primary color for off, and a disabled tone for unavailable.

Size and height parameters help on the mobile view, aim for a button at least 88 pixels tall, taking up roughly half the row's width alongside the scene button. Adjust to your own column layout. The goal, a finger lands correctly on the first try.

Button 2: the Office Evening scene (tap)

The scene.office_evening scene is an everyday household action. Tap activates the scene. A friendly card name, "Office Evening" or "Evening in the Office." No entity ID in the label.

A standard-version sketch reads type: custom:button-card, entity: scene.office_evening, name: Office Evening, icon: mdi:desk-lamp, show_state: false, a tap_action calling the scene.turn_on service targeted at that entity, a hold_action of more-info, and the same card styling as the LED button, rounded corners, padding, a bold name, a slightly larger icon.

This button lands on Start and the mobile view. The test scene, scene.office_test, doesn't get a Button Card beside it. One scene button on the household's screen, one everyday scene.

Button 3: the LED signal test (hold, Diagnostics only)

The script.office_led_signal script runs on hold, not on tap. This card lives exclusively on the Diagnostics or Admin view. Tap can open more-info or do nothing at all. Hold calls the script.

A standard-version sketch, with hold plus confirmation, on Diagnostics, reads type: custom:button-card, entity: script.office_led_signal, name: LED Signal Test, icon: mdi:led-strip-variant, show_state: false, a tap_action of none, and a hold_action calling the script.turn_on service targeted at that script, with a confirmation dialog reading "Run the office LED signal test?" The card styling stays simple, rounded corners, padding, and a warm-toned icon color as a visual cue.

Add a short markdown note beneath the button, "Hold to run the test." The admin knows what it does. The household never opens this view. Module 12's helpers stay on the entities list beside it, you don't need to move them into Button Card.

When someone suggests putting this same button on Start "to make testing more convenient," say no. A hold action on a diagnostic script sitting under your partner's thumb is a fast track to an accidental test at midnight.

Installing Button Card step by step

After downloading from HACS, enter edit mode on Start. If you already have Mushroom Entity cards for the LED and the scene from Lesson 2, you can swap them for Button Card, edit the card, change its type to custom:button-card, and paste the YAML sketch above. Or delete the old card and add a new one. Don't duplicate, one entity, one button on screen.

Button Card has rich documentation on RomRider's GitHub. This course uses its basics, entity, name, icon, tap_action, hold_action, show_state. Save advanced styling, custom fields, animations, multiple states, for Lesson 8's Card Mod work or your own experiments after the mini project.

After every button, test tap and hold separately. Tap on the scene should activate scene.office_evening. Hold on Diagnostics should run the script, a plain tap on that same button should not.

What never goes on a Button Card on Start

Restarting Home Assistant. Reloading YAML. script.office_led_signal on a plain tap. scene.office_test. And critical actions without confirmation attached.

A fallback plan

A fallback for the LED reverts to a plain type: tile card with the same entity and name. A fallback for the scene button reverts to a plain type: button card with a tap_action calling scene.turn_on against the same entity. Keep both sketches in your notes alongside the Pro versions.

Tap safety: what's never allowed on Start

In Module 13 you established that restarting Home Assistant and reloading YAML are service actions belonging to the Admin view, at the end of the Service section, often with an extra confirmation attached. Button Card doesn't change that rule. Don't put homeassistant.restart under a tap, not "just for yourself," not "because I have a hidden view."

The same prohibition applies to hold on Start, a long press on the evening scene shouldn't trigger the LED test script. Hold on a script belongs exclusively to Diagnostics or Admin. Treat the mobile view like Start, big buttons, zero risky actions under a thumb.

Never allowed, restarting HA under tap or hold on Start, script.office_led_signal on Start even hold-only, scene.office_test beside the evening scene, and test helpers wearing a Button Card on the hub.

A real-world example: hold triggered by accident

Someone on a forum put the test script's Button Card on Start "because it's convenient for testing." Their partner held the scene button, assuming a long press did nothing. The LED started blinking its test signal at seven in the evening. The logic worked correctly. The dashboard design didn't.

That's exactly why this lesson holds firmly to two tap buttons on Start and one hold button on Diagnostics. Simple rules are easier to maintain through future HA updates than "it'll probably work out."

Add a short markdown description next to the diagnostic button. Six months from now, the admin will still know that hold does something and tap doesn't.

A decision tree: Mushroom versus Button Card

Not sure which card to use? Walk through these questions in order, it's faster than installing both "just to try."

Are you assembling a description from several entities? Yes means Mushroom Template Card from Lesson 3. No, keep going. Do you need hold or double_tap? Yes means Button Card. No, keep going. Is this a big scene or LED button on Start? Yes means Button Card, this lesson. No, keep going. Is this navigation to another view? Yes means Mushroom Chips Card. No, keep going. Is this a single entity for reading or toggling? Yes means Mushroom Entity, or just leave the plain tile if that's enough, and on Diagnostics, leave it as entities.

You can genuinely have the Mushroom Template "Office Now" card and the scene's Button Card sitting side by side on Start. That's not duplication, Template describes state, Button performs the action. That's the intended Start Pro layout after this lesson.

Button Card versus Mushroom, compared

An entity tile with an icon and state calls for Mushroom Entity Card. A description built from several entities calls for Mushroom Template Card. A big scene or LED button calls for Button Card. And hold on a script, or a distinct on/off look, both call for Button Card too. You can genuinely keep Mushroom Template's "Office Now" and the scene's Button Card side by side on Start, that's not duplication, Template describes, Button acts.

Button size on the mobile view

On the mobile view, set two side-by-side Button Cards, the LED and the scene, with a size parameter around 20% and a card height of roughly 88 pixels. That's not a magic number, what matters is that the button reads taller than a system tile and has breathing room from its neighbor. Test with your thumb, not a mouse.

If you're working with a single column on the phone, you can give both buttons full width, size: 100%, and stack them one above the other. That way your partner won't land on the LED while reaching for the scene. Match whatever column layout Module 13 gave you and adjust only the height.

The script's button on Diagnostics can be wider and shorter, the admin uses it rarely, and a descriptive "hold" label matters more than Start-sized dimensions.

Laying out three buttons across the screen

On Start, a sensible layout runs, the markdown up top, Template or Entity for temperature, then a row of two Button Cards, the LED and the scene, side by side on desktop, stacked on the mobile view. Buttons should share a similar height so a finger doesn't land on the wrong element.

On Diagnostics, the script's button can sit beneath the entities list or in its own "Test Actions" section. What matters is visual separation from the helpers, the admin should be able to tell at a glance, entities are state, Button is action.

You don't need to prettify the whole Diagnostics list with Button Cards. One hold button on the script is enough. The rest stays system, exactly as in Module 13.

Button Card also allows visual states, a different icon when the LED's on versus off. That's an optional refinement, applied only after tap works correctly. Get the button reliably toggling the entity first, then add custom fields from RomRider's documentation. This course prioritizes safe tap and hold behavior over animation.

If a button stops working after a Button Card update, check the changelog in HACS, tap_action syntax occasionally shifts. Keep a backup of this lesson's view YAML in your notes.

Testing tap and hold before closing the lesson

Once your three buttons are configured, run a short test pass. On Start, tapping the LED should change switch.led_status_office's state, tapping the scene should activate scene.office_evening, a short tap, no holding. On Diagnostics, a plain tap on the script's button should do nothing or open more-info, only hold should run script.office_led_signal.

Run this test on both a phone and a desktop. Hold sometimes needs a longer press in a desktop browser than in the mobile app. If hold on Diagnostics fires the script during a short tap, change tap_action to none and keep only hold.

Note in your notebook which buttons you swapped from Mushroom to Button Card. In Lesson 5 you'll use the same layout on the Office Pro view.

Questions about Button Card

Do I need to delete the Mushroom Entity for the LED? Yes, if you're swapping it for Button Card. Two buttons for the same entity sitting side by side is just clutter. Can hold live on Start in some admin mode? Not in this course. Start and the mobile view are household screens. The script stays Diagnostics-only. Does Button Card replace entities on Diagnostics? No. Helpers and the timer stay on the list in flow order.

What can go wrong

A script on tap on Start means your partner triggers it by accident, hold belongs only on Diagnostics. A restart hidden under tap is a risk even when it's "hidden" inside hold, restart stays in the Service section on Admin. A test scene on Start puts two scene buttons side by side, the household clicks the wrong one. Missing the "Status LED" name leaves a raw switch entity ID on the household's screen. Button Card everywhere means even Diagnostics could stay plain entities, you don't need to prettify helpers. And a double action, tap and hold both wired to the same scene button with the script attached to hold, splits views instead, the scene on Start, the script on Diagnostics.

Assignment: three Button Card buttons

Install Button Card from HACS and refresh the Home Assistant page. Add a Status LED button, tap toggle, on Start. Add an Office Evening button, tap activates scene.office_evening. Add an LED Signal Test button on Diagnostics, hold-only, tap set to none or more-info. Confirm there's no restart, test scene, or helper anywhere on Start. And test the mobile view, big buttons, clear names.

Take a screenshot of Start with Button Card on your phone. It's the foundation for Lesson 5's Office Pro room card.

After this lesson you've got a full set of basic HACS cards on the household's dashboard, Mushroom Entity and Template for reading state, Button Card for action. Diagnostics can still look plain. That's deliberate, the admin sees Module 12's logic flow, the household sees Pro on Start and Office.

Key takeaways

What's next

In Lesson 5 you assemble the Office view into one block, Office Pro, the "Office Now" template, the Button Card controls, sections with no technical clutter. You've already got the building blocks from Lessons 2, 3, and 4. Now you arrange them into a room card.

Finish your three buttons and test hold on Diagnostics deliberately, not in a rush. A safe Dashboard Pro is one the household isn't afraid to touch. After this lesson, only the everyday buttons land on Start, the status LED and Office Evening. The test script stays off the household's screen.

If you're unsure whether a button belongs on Start, ask yourself, "could my partner tap this by accident at ten at night?" If yes, and the result is annoying or risky, move the action to Diagnostics or lock it behind a hold confirmation. Button Card gives you a beautiful button, but you're the one who decides what lands under the household's thumb.