# Button card

> The button card is a big, square button with an icon and a name. It runs one action, like toggling a light or activating a scene.

Source: https://contributors.home-assistant.io/design/dashboards/button-card/

Live demo of `hui-card`, connected to a demo Home Assistant.

```html
<hui-card style="width: 180px" data-props='{"config": {"type": "button", "entity": "light.living_room_lamp"}}'></hui-card>
<hui-card style="width: 180px" data-props='{"config": {"type": "button", "entity": "scene.movie_night"}}'></hui-card>
<hui-card style="width: 180px" data-props='{"config": {"type": "button", "entity": "lock.front_door"}}'></hui-card>
```

## Usage

The button card is one large target: an icon with a name below it. Selecting it runs an action. For entities that can be toggled, like a light, a switch, or a fan, that is a toggle. For all other entities, it opens the more-info dialog. Holding the button opens the more-info dialog too.

Use a button card when one action matters most, and people want to hit it without looking twice, like on a wall tablet. For most entities, the [tile card](https://contributors.home-assistant.io/design/dashboards/tile-card/) is a better fit: it shows the state, takes less room, and can add more controls with features.

A button card does not need an entity. Without one, it is a plain button that runs its `tap_action`, like navigating to another dashboard or performing an action.

### Show state

The button shows the name and the icon. Add `show_state: true` to show the state below the name, and use `show_name` and `show_icon` to hide either one. An icon-only button needs an entity whose icon says enough on its own.

Live demo of `hui-card`, connected to a demo Home Assistant.

```html
<hui-card style="width: 180px" data-props='{"config": {"type": "button", "entity": "light.hallway", "show_state": true}}'></hui-card>
<hui-card style="width: 180px" data-props='{"config": {"type": "button", "entity": "switch.desk_plug", "show_name": false}}'></hui-card>
<hui-card style="width: 180px" data-props='{"config": {"type": "button", "entity": "light.kitchen_ceiling", "show_icon": false, "show_state": true}}'></hui-card>
```

### Icon size

By default, the icon scales with the card: it takes 40% of the width of the card. Set `icon_height`, like `40px`, for a fixed, smaller icon and a calmer button. A grid of buttons reads better when all of them use the same height.

Live demo of `hui-card`, connected to a demo Home Assistant.

```html
<hui-card style="width: 180px" data-props='{"config": {"type": "button", "entity": "light.living_room_lamp", "icon_height": "40px"}}'></hui-card>
<hui-card style="width: 180px" data-props='{"config": {"type": "button", "entity": "light.hallway", "icon_height": "40px"}}'></hui-card>
```

### Content

- Keep the name to a word or two. It sits under the icon, centered, and wraps quickly.
- Make the action predictable. If the button does something else than toggle, like run a script, the name should say what happens.
- Group buttons with a [grid card](https://contributors.home-assistant.io/design/dashboards/grid-card/) so they line up.

## Configuration

- `entity` (string): the entity the button is for.
- `name` (string): the name to show. Defaults to the name of the entity.
- `icon` (string): the icon to show. Defaults to the icon of the entity.
- `icon_height` (string): the height of the icon, like `40px`. By default, the icon scales with the width of the card.
- `color` (string): the color of the icon when the entity is active. Defaults to `state`, the color of the state. Use `none` for the default icon color.
- `show_name` (boolean): shows the name. Defaults to `true`.
- `show_icon` (boolean): shows the icon. Defaults to `true`.
- `show_state` (boolean): shows the state. Defaults to `false`.
- `theme` (string): the theme to use for this card.
- `tap_action` (action): what happens when you select the button. Defaults to `toggle` for entities that can be toggled, and `more-info` for the rest.
- `hold_action` (action): what happens when you hold the button. Defaults to `more-info`.
- `double_tap_action` (action): what happens when you double tap the button. Defaults to `none`.

```yaml
type: button
entity: scene.movie_night
icon_height: "40px"
tap_action:
  action: perform-action
  perform_action: scene.turn_on
  target:
    entity_id: scene.movie_night
```

The old type name `entity-button` still works. It creates the same button, but needs an `entity`.

## In code

The card lives in [`src/panels/lovelace/cards/hui-button-card.ts`](https://github.com/home-assistant/frontend/blob/dev/src/panels/lovelace/cards/hui-button-card.ts), and the element is `<hui-button-card>`. The `entity-button` type is `<hui-entity-button-card>` in `hui-entity-button-card.ts`, a small subclass that only adds the check for an entity.

In the sections view, a button with an icon and a name or state takes 6 of the 12 columns and two rows. A button with only an icon or only text takes 3 columns and one row. Both can shrink to 2 columns.

[Source](https://github.com/home-assistant/frontend/blob/dev/src/panels/lovelace/cards/hui-button-card.ts)