2019-02-24 04:58:41 +08:00
# Button Card
2019-02-24 04:57:23 +08:00
2019-02-24 04:55:19 +08:00
[![GitHub Release][releases-shield]][releases]
[![License][license-shield]](LICENSE.md)
2019-02-24 04:55:41 +08:00
![Project Maintenance][maintenance-shield]
2019-02-24 04:55:19 +08:00
[![GitHub Activity][commits-shield]][commits]
[![Discord][discord-shield]][discord]
[![Community Forum][forum-shield]][forum]
2019-02-23 08:21:18 +08:00
2018-10-06 18:10:54 +08:00
Lovelace Button card for your entities.
2018-08-26 23:52:54 +08:00
2018-09-04 01:38:48 +08:00
2018-08-28 08:06:51 +08:00
## Features
2019-04-18 08:30:57 +08:00
- works with any toggleable entity
2019-04-22 02:50:44 +08:00
- 6 available actions on **tap** and/or **hold** : `none` , `toggle` , `more-info` , `navigate` , `url` and `call-service`
2019-04-18 08:30:57 +08:00
- state display (optional)
- custom color (optional), or based on light rgb value
- custom state definition with customizable color, icon and style (optional)
- custom size (optional)
- custom icon (optional)
- custom css style (optional)
2019-04-23 15:13:54 +08:00
- multiple [layout ](#Layout ) support
- units can be redefined or hidden
2019-04-18 08:30:57 +08:00
- 2 color types
- `icon` : apply color settings to the icon only
- `card` : apply color settings to the card only
- automatic font color if color_type is set to `card`
- support unit of measurement
- blank card and label card (for organization)
- [blink ](#blink ) animation support
2019-04-20 00:33:07 +08:00
- rotating animation support
- confirmation popup for sensitive items (optional)
2019-04-25 16:15:57 +08:00
- haptic support for the [Beta IOS App ](http://home-assistant.io/ios/beta )
2019-04-18 08:30:57 +08:00
- support for [custom_updater ](https://github.com/custom-components/custom_updater )
2018-08-26 23:52:54 +08:00
2019-04-18 07:03:57 +08:00
## Configuration
2019-04-18 08:30:57 +08:00
2019-04-18 07:03:57 +08:00
### Main Options
2019-04-20 02:16:47 +08:00
| Name | Type | Default | Supported options | Description |
| -------------- | ----------- | ------------ | ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | string | **Required** | `custom:button-card` | Type of the card |
2019-04-25 15:45:04 +08:00
| `entity` | string | optional | `switch.ac` | entity_id |
2019-04-20 02:16:47 +08:00
| `icon` | string | optional | `mdi:air-conditioner` | Icon to display. Will be overriden by the icon defined in a state (if present). Defaults to the entity icon. Hide with `show_icon: false` |
| `color_type` | string | `icon` | `icon` \| `card` \| `blank-card` \| `label-card` | Color either the background of the card or the icon inside the card. Setting this to `card` enable automatic `font` and `icon` color. This allows the text/icon to be readable even if the background color is bright/dark. Additional color-type options `blank-card` and `label-card` can be used for organisation (see examples). |
| `color` | string | optional | `auto` \| `rgb(28, 128, 199)` | Color of the icon/card. `auto` sets the color based on the color of a light. By default, if the entity state is `off` , the color will be `var(--paper-item-icon-active-color)` , for `on` it will be `var(--paper-item-icon-color)` and for any other state it will be `var(--primary-text-color)` . You can redefine each colors using `state` |
| `size` | string | `40%` | `20px` | Size of the icon. Can be percentage or pixel |
2019-04-22 02:50:44 +08:00
| `tap_action` | object | optional | See [Action ](#Action ) | Define the type of action on click, if undefined, toggle will be used. |
2019-04-25 15:45:04 +08:00
| `hold_action` | object | optional | See [Action ](#Action ) | Define the type of action on hold, if undefined, nothing happens. |
2019-04-20 02:16:47 +08:00
| `name` | string | optional | `Air conditioner` | Define an optional text to show below the icon |
2019-04-20 12:44:35 +08:00
| `show_name` | boolean | `true` | `true` \| `false` | Wether to show the name or not. Will pick entity_id's name by default, unless redefined in the `name` property or in any state `name` property |
2019-04-20 02:16:47 +08:00
| `show_state` | boolean | `false` | `true` \| `false` | Show the state on the card. defaults to false if not set |
| `show_icon` | boolean | `true` | `true` \| `false` | Wether to show the icon or not. Unless redefined in `icon` , uses the default entity icon from hass |
2019-04-23 15:13:54 +08:00
| `show_units` | boolean | `true` | `true` \| `false` | Display or hide the units of a sensor, if any. |
2019-04-26 07:00:50 +08:00
| `show_entity_picture` | boolean | `false` | `true` \| `false` | Replace the icon by the entity picture (if any) or the custom picture (if any). Falls back to using the icon if both are undefined |
| `entity_picture` | string | optional | Can be any of `/local/*` file or a URL | Will override the icon/the default entity_picture with your own image. Best is to use a square image. You can also define one per state |
2019-04-23 15:13:54 +08:00
| `units` | string | optional | `Kb/s` , `lux` , ... | Override or define the units to display after the state of the entity. If omitted, it's using the entity's units |
2019-04-20 02:16:47 +08:00
| `style` | object list | optional | `- text-transform: none` | Define a list of css attribute and their value to apply to the card |
2019-04-26 07:00:50 +08:00
| `entity_picture_style` | object list | optional | `- border-radius: 50%` , `- filter: grayscale(100%)` , ... | Style applied to the entity picture |
2019-04-20 02:16:47 +08:00
| `state` | object list | optional | See [State ](#State ) | State to use for the color, icon and style of the button. Multiple states can be defined |
2019-04-22 14:04:11 +08:00
| `confirmation` | string | optional | Free-form text | Show a confirmation popup on tap with defined text |
2019-04-23 15:13:54 +08:00
| `layout` | string | optional | See [Layout ](#Layout ) | The layout of the button can be modified using this option |
2019-04-18 07:03:57 +08:00
### Action
2019-04-20 02:21:15 +08:00
| Name | Type | Default | Supported options | Description |
| ----------------- | ------ | -------- | ---------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `action` | string | `toggle` | `more-info` , `toggle` , `call-service` , `none` , `navigate` , `url` | Action to perform |
| `navigation_path` | string | none | Eg: `/lovelace/0/` | Path to navigate to (e.g. `/lovelace/0/` ) when action defined as navigate |
| `url` | string | none | Eg: `https://www.google.fr` | URL to open on click when action is `url` . The URL will open in a new tab |
| `service` | string | none | Any service | Service to call (e.g. `media_player.media_play_pause` ) when `action` defined as `call-service` |
| `service_data` | object | none | Any service data | Service data to include (e.g. `entity_id: media_player.bedroom` ) when `action` defined as `call-service` |
2019-04-25 16:15:57 +08:00
| `haptic` | string | none | `success` , `warning` , `failure` , `light` , `medium` , `heavy` , `selection` | Haptic feedback for the [Beta IOS App ](http://home-assistant.io/ios/beta ) |
2019-04-18 07:03:57 +08:00
### State
2019-04-20 02:16:47 +08:00
| Name | Type | Default | Supported options | Description |
| ---------- | ------------- | ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| `operator` | string | `==` | See [Available Operators ](#Available-operators ) | The operator used to compare the current state against the `value` |
| `value` | string/number | **required** (unless operator is `default` ) | If your entity is a sensor with numbers, use a number directly, else use a string | The value which will be compared against the current state of the entity |
2019-04-20 12:44:35 +08:00
| `name` | string | optional | Any string, `'Alert'` , `'My little switch is on'` , ... | if `show_name` is `true` , the name to display for this state. If undefined, uses the general config `name` , and if undefined uses the entity name |
2019-04-20 02:16:47 +08:00
| `icon` | string | optional | `mdi:battery` | The icon to display for this state. Defaults to the entity icon. Hide with `show_icon: false` |
| `color` | string | `var(--primary-text-color)` | Any color, eg: `rgb(28, 128, 199)` or `blue` | The color of the icon (if `color_type: icon` ) or the background (if `color_type: card` ) |
| `style` | string | optional | Any CSS style. If nothing is specified, the main style is used unless undefined. If you want to override the default style of the main part of the config, use `style: []` | Define a list of css attribute and their value to apply to the card |
| `spin` | boolean | `false` | `true` \| `false` | Should the icon spin for this state? |
2019-04-26 07:00:50 +08:00
| `entity_picture` | string | optional | Can be any of `/local/*` file or a URL | Will override the icon/the default entity_picture with your own image for this state. Best is to use a square image |
| `entity_picture_style` | object list | optional | `- border-radius: 50%` , `- filter: grayscale(100%)` , ... | Style applied to the entity picture for this state |
2019-04-18 07:03:57 +08:00
### Available operators
| Operator | `value` example | Description |
| :-------: | --------------- | -------------------------------------------------------------------------------------------------------- |
| `<` | `5` | Current state is inferior to `value` |
| `<=` | `4` | Current state is inferior or equal to `value` |
| `==` | `42` or `'on'` | **This is the default if no operator is specified.** Current state is equal (`==` javascript) to `value` |
| `>=` | `32` | Current state is superior or equal to `value` |
| `>` | `12` | Current state is superior to `value` |
| `!=` | `'normal'` | Current state is not equal (`!=` javascript) to `value` |
| `regex` | `'^norm.*$'` | `value` regex applied to current state does match |
| `default` | N/A | If nothing matches, this is used |
2019-04-23 15:13:54 +08:00
### Layout
This option enables you to modify the layout of the card.
It is fully compatible with every `show_*` option. Make sure you set `show_state: true` if you want to show the state
Multiple values are possible, see the image below for examples:
* `vertical` (default value if nothing is provided): Everything is centered vertically on top of each other
* `icon_name_state` : Everything is aligned horizontally, name and state are concatenated
* `name_state` : Icon sits on top of name and state concatenated on one line
* `icon_name` : Icon and name are horizontally aligned, state is centered below
* `icon_state` : Icon and state are horizontally aligned, name is centered below
* `icon_name_state2nd` : Icon, name and state are horizontally aligned, name is above state
* `icon_state_name2nd` : Icon, name and state are horizontally aligned, state is above name
2019-04-18 07:03:57 +08:00
## Installation
2019-04-18 08:30:57 +08:00
2019-02-23 08:06:43 +08:00
### Manual Installation
2019-04-26 00:38:41 +08:00
1. Download the [button-card ](https://raw.githubusercontent.com/custom-cards/button-card/master/dist/button-card.js )
2018-08-28 08:06:51 +08:00
2. Place the file in your `config/www` folder
3. Include the card code in your `ui-lovelace-card.yaml`
2019-02-23 08:06:43 +08:00
2018-08-26 23:52:54 +08:00
```yaml
title: Home
resources:
- url: /local/button-card.js
type: module
```
2019-02-23 08:06:43 +08:00
2018-08-28 08:06:51 +08:00
4. Write configuration for the card in your `ui-lovelace.yaml`
2019-02-23 08:06:43 +08:00
### Installation and tracking with `custom_updater`
2018-09-04 01:38:48 +08:00
2019-02-23 08:06:43 +08:00
1. Make sure the [custom_updater ](https://github.com/custom-components/custom_updater ) component is installed and working.
2. Configure Lovelace to load the card.
2018-09-04 01:38:48 +08:00
2019-02-23 08:06:43 +08:00
```yaml
resources:
- url: /customcards/github/custom-cards/button-card.js?track=true
type: module
2018-09-04 01:38:48 +08:00
```
2019-02-23 08:06:43 +08:00
3. Run the service `custom_updater.check_all` or click the "CHECK" button if you use the [`tracker-card` ](https://github.com/custom-cards/tracker-card ).
4. Refresh the website.
2018-09-04 01:38:48 +08:00
2018-08-28 08:06:51 +08:00
## Examples
2019-04-18 07:03:57 +08:00
Show a button for the air conditioner (blue when on, `var(--disabled-text-color)` when off):
2018-09-02 11:31:47 +08:00
2018-09-04 01:38:48 +08:00
2018-09-02 11:31:47 +08:00
2018-08-26 23:52:54 +08:00
```yaml
- type: "custom:button-card"
entity: switch.ac
icon: mdi:air-conditioner
color: rgb(28, 128, 199)
```
2019-04-18 07:03:57 +08:00
Redefine the color when the state if off to red:
2019-04-18 08:30:57 +08:00
2019-04-18 07:03:57 +08:00
```yaml
- type: "custom:button-card"
entity: switch.ac
icon: mdi:air-conditioner
color: rgb(28, 128, 199)
state:
2019-04-18 08:30:57 +08:00
- value: "off"
2019-04-18 07:03:57 +08:00
color: rgb(255, 0, 0)
```
2019-04-18 08:30:57 +08:00
---
2018-08-26 23:52:54 +08:00
2018-08-28 08:06:51 +08:00
Show an ON/OFF button for the home_lights group:
2018-09-02 11:31:47 +08:00
2018-09-04 01:38:48 +08:00
2018-09-02 11:31:47 +08:00
2018-08-26 23:52:54 +08:00
```yaml
- type: "custom:button-card"
entity: group.home_lights
2019-04-19 03:12:46 +08:00
show_icon: false
2018-09-02 11:31:47 +08:00
show_state: true
2018-08-26 23:52:54 +08:00
```
2018-08-28 08:06:51 +08:00
2019-04-18 08:30:57 +08:00
---
2018-09-02 11:31:47 +08:00
2018-09-04 01:38:48 +08:00
Light entity with custom icon and "more info" pop-in:
2018-09-02 11:31:47 +08:00
2018-09-04 01:38:48 +08:00
2018-09-02 11:31:47 +08:00
2018-08-28 08:06:51 +08:00
```yaml
- type: "custom:button-card"
entity: light.living_room_lights
icon: mdi:sofa
2018-09-02 11:31:47 +08:00
color: auto
2019-04-18 07:03:57 +08:00
tap_action:
action: more-info
2018-08-28 08:06:51 +08:00
```
2019-04-18 08:30:57 +08:00
---
2018-09-02 11:31:47 +08:00
Light card with card color type, name, and automatic color:
2018-09-04 01:38:48 +08:00
2018-09-02 11:31:47 +08:00
```yaml
- type: "custom:button-card"
entity: light._
icon: mdi:home
color: auto
color_type: card
2019-04-18 07:03:57 +08:00
tap_action:
action: more-info
2018-09-02 11:31:47 +08:00
name: Home
style:
- font-size: 12px
- font-weight: bold
```
2019-04-18 08:30:57 +08:00
---
2018-09-02 11:31:47 +08:00
2018-09-04 01:38:48 +08:00
Horizontal stack with :
2018-09-02 11:31:47 +08:00
2019-04-18 08:30:57 +08:00
- 2x blank cards
- 1x volume up button with service call
- 1x volume down button with service call
- 2x blank cards
2018-09-02 11:31:47 +08:00
2019-04-18 08:30:57 +08:00
2018-09-02 11:31:47 +08:00
```yaml
- type: horizontal-stack
cards:
- type: "custom:button-card"
2018-09-04 01:38:48 +08:00
color_type: blank-card
- type: "custom:button-card"
color_type: blank-card
- type: "custom:button-card"
2018-09-02 11:31:47 +08:00
color_type: card
2018-09-04 01:38:48 +08:00
color: rgb(223, 255, 97)
icon: mdi:volume-plus
2019-04-18 07:03:57 +08:00
tap_action:
2019-04-26 23:54:55 +08:00
action: call-service
2019-04-18 07:03:57 +08:00
service: media_player.volume_up
service_data:
2018-09-04 01:38:48 +08:00
entity_id: media_player.livimg_room_speaker
2018-09-02 11:31:47 +08:00
- type: "custom:button-card"
2018-09-04 01:38:48 +08:00
color_type: card
color: rgb(223, 255, 97)
icon: mdi:volume-minus
2019-04-18 07:03:57 +08:00
tap_action:
2019-04-26 23:54:55 +08:00
action: call-service
2019-04-18 07:03:57 +08:00
service: media_player.volume_down
service_data:
2018-09-04 01:38:48 +08:00
entity_id: media_player.livimg_room_speaker
2018-09-02 11:31:47 +08:00
- type: "custom:button-card"
2018-09-04 01:38:48 +08:00
color_type: blank-card
2018-09-02 11:31:47 +08:00
- type: "custom:button-card"
2018-09-04 01:38:48 +08:00
color_type: blank-card
2018-09-02 11:31:47 +08:00
```
2019-04-18 08:30:57 +08:00
---
2018-10-09 22:08:39 +08:00
Vertical Stack with :
2019-04-18 08:30:57 +08:00
- 1x label card
- Horizontal Stack with :
- 1x Scene 1 Button
- 1x Scene 2 Button
- 1x Scene 3 Button
- 1x Scene 4 Button
- 1x Scene Off Button
2018-10-09 22:08:39 +08:00
2019-04-18 08:30:57 +08:00
2018-10-09 22:08:39 +08:00
```yaml
- type: vertical-stack
cards:
- type: "custom:button-card"
color_type: label-card
color: rgb(44, 109, 214)
name: Kitchen
- type: horizontal-stack
cards:
- type: "custom:button-card"
entity: switch.kitchen_scene_1
color_type: card
color: rgb(66, 134, 244)
icon: mdi:numeric-1-box-outline
- type: "custom:button-card"
entity: switch.kitchen_scene_2
color_type: card
color: rgb(66, 134, 244)
icon: mdi:numeric-2-box-outline
- type: "custom:button-card"
entity: switch.kitchen_scene_3
color_type: card
color: rgb(66, 134, 244)
icon: mdi:numeric-3-box-outline
- type: "custom:button-card"
entity: switch.kitchen_scene_4
color_type: card
color: rgb(66, 134, 244)
icon: mdi:numeric-4-box-outline
- type: "custom:button-card"
entity: switch.kitchen_off
color_type: card
color: rgb(66, 134, 244)
icon: mdi:eye-off-outline
```
2019-01-15 04:09:31 +08:00
### Configuration with states
2019-04-18 08:30:57 +08:00
2019-01-15 04:09:31 +08:00
Input select card with select next service and custom color and icon for states. In the example below the icon `mdi:cube-outline` will be used when value is `sleeping` and `mdi:cube` in other cases.
2018-10-16 10:58:20 +08:00
2019-04-13 23:07:02 +08:00
#### Default behavior
2019-04-18 08:30:57 +08:00
2019-04-18 07:03:57 +08:00
If you don't specify any operator, `==` will be used to match the current state against the `value`
2019-04-18 08:30:57 +08:00
2018-10-16 10:58:20 +08:00
```yaml
2019-04-18 07:03:57 +08:00
- type: "custom:button-card"
entity: input_select.cube_mode
icon: mdi:cube
tap_action:
2019-04-26 23:54:55 +08:00
action: call-service
2019-04-18 23:16:36 +08:00
service: input_select.select_next
service_data:
entity_id: input_select.cube_mode
2019-04-18 07:03:57 +08:00
show_state: true
state:
2019-04-18 08:30:57 +08:00
- value: "sleeping"
2019-04-18 07:03:57 +08:00
color: var(--disabled-text-color)
icon: mdi:cube-outline
2019-04-18 08:30:57 +08:00
- value: "media"
2019-04-18 07:03:57 +08:00
color: rgb(5, 147, 255)
2019-04-18 08:30:57 +08:00
- value: "light"
2019-04-18 07:03:57 +08:00
color: rgb(189, 255, 5)
2018-10-16 10:58:20 +08:00
```
2019-04-13 23:07:02 +08:00
#### With Operator on state
2019-04-18 08:30:57 +08:00
2019-04-13 23:07:02 +08:00
The definition order matters, the first item to match will be the one selected.
2019-04-18 08:30:57 +08:00
2019-04-13 23:07:02 +08:00
```yaml
2019-04-18 07:03:57 +08:00
- type: "custom:button-card"
entity: sensor.temperature
show_state: true
state:
- value: 15
operator: '< ='
color: blue
icon: mdi:thermometer-minus
- value: 25
operator: '>='
color: red
icon: mdi:thermometer-plus
- operator: 'default' # used if nothing matches
color: yellow
icon: mdi: thermometer
style:
- opacity: 0.5
2019-04-13 23:07:02 +08:00
```
2019-04-19 14:22:39 +08:00
#### `tap_action` Navigate
2019-04-18 08:30:57 +08:00
2019-04-19 14:22:39 +08:00
Buttons can link to different views using the `navigate` action:
2019-04-18 08:30:57 +08:00
2019-04-18 07:03:57 +08:00
```yaml
- type: "custom:button-card"
color_type: label-card
icon: mdi:home
name: Go To Home
tap_action:
2019-04-19 14:22:39 +08:00
action: navigate
2019-04-18 07:03:57 +08:00
navigation_path: /lovelace/0
```
2018-09-02 11:31:47 +08:00
2019-04-19 14:22:39 +08:00
The `navigation_path` also accepts any Home Assistant internal URL such as /dev-info or /hassio/dashboard for example.
2019-04-18 07:03:57 +08:00
#### blink
2019-04-18 08:30:57 +08:00
2019-04-18 07:03:57 +08:00
You can make the whole button blink:
2019-04-20 12:44:35 +08:00
2019-04-18 07:03:57 +08:00
2019-04-18 08:30:57 +08:00
2019-04-18 07:03:57 +08:00
```yaml
- type: "custom:button-card"
color_type: card
entity: binary_sensor.intruder
name: Intruder Alert
state:
2019-04-18 08:30:57 +08:00
- value: "on"
2019-04-18 07:03:57 +08:00
color: red
icon: mdi:alert
style:
- animation: blink 2s ease infinite
- operator: default
color: green
icon: mdi:shield-check
```
2018-09-02 11:31:47 +08:00
2018-08-28 08:06:51 +08:00
## Credits
2019-04-18 08:30:57 +08:00
- [ciotlosm ](https://github.com/ciotlosm ) for the readme template and the awesome examples
2019-02-24 04:55:19 +08:00
2019-02-26 10:30:02 +08:00
[commits-shield]: https://img.shields.io/github/commit-activity/y/custom-cards/button-card.svg?style=for-the-badge
2019-02-24 04:55:19 +08:00
[commits]: https://github.com/custom-cards/button-card/commits/master
[discord]: https://discord.gg/Qa5fW2R
2019-03-17 04:18:30 +08:00
[discord-shield]: https://img.shields.io/discord/330944238910963714.svg?style=for-the-badge
2019-02-26 10:30:02 +08:00
[forum-shield]: https://img.shields.io/badge/community-forum-brightgreen.svg?style=for-the-badge
2019-02-24 04:55:19 +08:00
[forum]: https://community.home-assistant.io/t/lovelace-button-card/65981
2019-02-26 10:30:02 +08:00
[license-shield]: https://img.shields.io/github/license/custom-cards/button-card.svg?style=for-the-badge
2019-03-17 04:18:30 +08:00
[maintenance-shield]: https://img.shields.io/maintenance/yes/2019.svg?style=for-the-badge
2019-02-26 10:30:02 +08:00
[releases-shield]: https://img.shields.io/github/release/custom-cards/button-card.svg?style=for-the-badge
2019-02-24 04:55:19 +08:00
[releases]: https://github.com/custom-cards/button-card/releases
