spin (to make the icon/entity_picture rotate) has
been renamed to rotate, please update your configurations- triggers_update:
triggers_update is deprecated and will not have any
effect if set. Entities are discovered automatically. If there is no
suitable entities in your configuration, consider using update_timer
to update the card on interval.
- variables:
variables are only evaluated if they are "used" so
hacks using variables to run javascript code during card init for eg.
should read the updated documentation section. It is still possible with
the force_eval variables configuration option.
type: custom:button-card
entity: switch.skylight
update_timer: 1s
variables:
always_evaled:
value: '[[[ window.alwaysEvaled = `${new Date().getTime()}`; ]]]'
force_eval: true
never_evaled: '[[[ window.neverEvaled = `${new Date().getTime()}`; ]]]'
name: 'always should update every second,<br/>never should be unset'
show_label: true
label: |
[[[
return `always: ${window.alwaysEvaled || "not set"}
<br/>never: ${window.neverEvaled || "not set"}`;
]]]type: custom:button-card
variables:
never_evaled: '[[[ throw new Error("This variable should never be evaluated") ]]]'
aa:
value: '[[[ return "Test variables dependencies: OK" ]]]'
test1: '[[[ return variables.aa ]]]'
name: '[[[ return variables.test1; ]]]'
triggers_update is not required anymore, all entities used in JS templates are now discovered automatically. (#1080) (ccb5766), closes #1074- custom_fields: New
force_recreate: true to recreate the nested card on each config update (#1102) (0a85dff), closes #1086
- extra_styles:
extra_styles is now merged when using config templates instead of being overriden by the last one set (#1108) (a4d78e1), closes #name #name #name
- new
helpers.runAction to run any action supported by button-card (#1075) (295afcc)
- rename
spin to rotate (#1098) (d26bae2), closes #1081
- ripple:
show_ripple to disable or enable the ripple/hover effect (undefined = auto) (#1076) (1964f4b)
- spin: Make
spin available as a main config option and support JS templates (#1084) (3c92a5d), closes #1081
- triggers_update:
triggers_update is deprecated and will not have any effect. This is now automatic. (#1095) (45a6b69)
- variables: variables can depend on any other variable (no alphabetical dependency anymore) (#1089) (f372ce4)
press_action would not work on touchscreen (#1100) (ea71b3d), closes #1097- actions: Haptic support. Requires Home Assistant 2025.11 to correctly override native Home Assistant Haptics (#1091) (6d9457d), closes #956 #565
- variables: Fixed a type error when a variable is
null (#1110) (05f1631), closes #1109
- variables: read only error in some cases (#1101) (a316aa2), closes #1099
- variables: storing objects or functions in variables would fail in specific cases (#1103) (4778c4a)
- variables: variables loops would not be detected anymore (80206ba)
- extra_styles:
extra_styles is now merged when using config templates instead of being overriden by the last one set (#1108) (a4d78e1), closes #name #name #name
- variables: Fixed a type error when a variable is
null (#1110) (05f1631), closes #1109
- actions: Haptic support. Requires Home Assistant 2025.11 to correctly override native Home Assistant Haptics (#1091) (6d9457d), closes #956 #565
- variables: variables loops would not be detected anymore (80206ba)
- custom_fields: New
force_recreate: true to recreate the nested card on each config update (#1102) (0a85dff), closes #1086
- variables: storing objects or functions in variables would fail in specific cases (#1103) (4778c4a)
spin (to make the icon/entity_picture rotate) has
been renamed to rotate, please update your configurations
- triggers_update:
triggers_update is deprecated and will not have any
effect if set. Entities are discovered automatically. If there is no
suitable entities in your configuration, consider using update_timer
to update the card on interval.
- variables:
variables are only evaluated if they are "used" so
hacks using variables to run javascript code during card init for eg.
should read the updated documentation section. It is still possible with
the force_eval variables configuration option.
type: custom:button-card
entity: switch.skylight
update_timer: 1s
variables:
always_evaled:
value: '[[[ window.alwaysEvaled = `${new Date().getTime()}`; ]]]'
force_eval: true
never_evaled: '[[[ window.neverEvaled = `${new Date().getTime()}`; ]]]'
name: 'always should update every second,<br/>never should be unset'
show_label: true
label: |
[[[
return `always: ${window.alwaysEvaled || "not set"}
<br/>never: ${window.neverEvaled || "not set"}`;
]]]type: custom:button-card
variables:
never_evaled: '[[[ throw new Error("This variable should never be evaluated") ]]]'
aa:
value: '[[[ return "Test variables dependencies: OK" ]]]'
test1: '[[[ return variables.aa ]]]'
name: '[[[ return variables.test1; ]]]'
- spin: Make
spin available as a main config option and support JS templates (#1084) (3c92a5d), closes #1081
- triggers_update:
triggers_update is deprecated and will not have any effect. This is now automatic. (#1095) (45a6b69)
- variables: variables can depend on any other variable (no alphabetical dependency anymore) (#1089) (f372ce4)
triggers_update is not required anymore, all entities used in JS templates are now discovered automatically. (#1080) (ccb5766), closes #1074
- Fix action config table format (f65b2a6)
- new
helpers.runAction to run any action supported by button-card (#1075) (295afcc)
- ripple:
show_ripple to disable or enable the ripple/hover effect (undefined = auto) (#1076) (1964f4b)
- Fix toast action table formating (af8c932)
- Remove uneeded
- from code examples (b202a09)
- tooltips: Tooltips have been migrated to use Home Assistant
tooltips (ha-tooltip) and will now show in the standard Home Assistant
style. There must be a button action for toolips to show as they fire
off pointer events. Review documentation for impact and updated styling
options. Requires Home Assistant 2025.10 and greater.
disable_kbd option to disable keyboard capture on the card (#1040) (f108a52), closes #1032- action: new
toast custom action and new helpers.toastMessage and helpers.toast helpers functions (#1070) (ecf1b5c)
- actions: call multiple actions in a row for any
*_action or icon_*_action with the new multi-actions action (#1041) (e3a50d8)
- actions: confirmation support for javascript, PIN & Password confirmation support (#1033) (6632114), closes #1030
- protect: allow configuring
protect at the card level (#1049) (1680330), closes #1044
- protect: Support for
success_message (#1048) (78c7151), closes #1046
- spinner: Display a configurable spinning wheel (eg. while a script is running) (#1047) (fb1963e)
- Support templates for
hidden to hide the card completely (#1013) (263d366), closes #1004
- tooltips: Migrate tooltips to ha-tooltip (#1063) (561003e), closes #1062
- tooltips: replace ha-tooltip with wa-tooltip and expose more styling (#1072) (c97f4dd), closes #1071
- custom_fields cards are not recreated from scratch anymore if their config is modified (#1064) (2d8aaa4), closes #1060
- improve spinner's default color for
color_type: card (#1065) (6db839d), closes #1058
- tooltip: Set default z-index so long/wide tooltips are always visible. (#1039) (45033df), closes #1035
- Update --button-card-riple-hover-opacity to 0.04 to match HA button defaults (#1037) (17917b8), closes #1036
- New documentation website replacing the current README (#1073) (2de1890)
- action: new
toast custom action and new helpers.toastMessage and helpers.toast helpers functions (#1070) (ecf1b5c)
- tooltips: replace ha-tooltip with wa-tooltip and expose more styling (#1072) (c97f4dd), closes #1071
- tooltips: Tooltips have been migrated to use Home Assistant
tooltips (ha-tooltip) and will now show in the standard Home Assistant
style. There must be a button action for toolips to show as they fire
off pointer events. Review documentation for impact and updated styling
options. Requires Home Assistant 2025.10 and greater.
- Support templates for
hidden to hide the card completely (#1013) (263d366), closes #1004
- custom_fields cards are not recreated from scratch anymore if their config is modified (#1064) (2d8aaa4), closes #1060
- protect: allow configuring
protect at the card level (#1049) (1680330), closes #1044
- protect: Support for
success_message (#1048) (78c7151), closes #1046
- spinner: Display a configurable spinning wheel (eg. while a script is running) (#1047) (fb1963e)
disable_kbd option to disable keyboard capture on the card (#1040) (f108a52), closes #1032- actions: call multiple actions in a row for any
*_action or icon_*_action with the new multi-actions action (#1041) (e3a50d8)
- actions: confirmation support for javascript, PIN & Password confirmation support (#1033) (6632114), closes #1030
- tooltip: Set default z-index so long/wide tooltips are always visible. (#1039) (45033df), closes #1035
- Update --button-card-riple-hover-opacity to 0.04 to match HA button defaults (#1037) (17917b8), closes #1036
- actions: complex templates would break in specific cases (#1029) (854b96a), closes #1028
- actions:
*_action and icon_*_action stricly follow what is
allowed in the configuration of this card (see updated documentation).
If you used some hacks, it might break. If those hacks were created to
run javascript code, you can now use action: javascript instead.
- actions: Some of you were using hacks to execute javascript
actions. This release officially implements
action: javascript and
this is the only supported way to execute javascript actions going
forward. Any other configuration might execute the javascript action
while the card is first displayed. Please update your config accordingly
and read the updated documentation.
- actions: CSS variables
--mdc-ripple-* are no longer supported.
These have been replaced with --button-card-ripple-* variables. You
will need to update your configuration.
- color: Card background color will always be
var (--card-background-color) when state is inactive and color_type: card. You can set card background with state.
- actions: avoid executing invalid actions configurations (#1023) (fe05b52)
- color: inactive card background no longer inactive color when
colour_type: card and color set. (#987) (b4f00f9), closes #754
- console error on click introduced in 5.0.0-dev.1 (fc39748), closes #1001
- double triggers with icon_*_actions (d9725d7)
- Embedded light card handle issue (#989) (d01ef37), closes #427 #901
- Event propagation to parent would not propagate the event properties (#1017) (a2051d4), closes #1015
- Hold action on picture entity (#996) (9f2501f), closes #994
- Move while hold on touch devices (#993) (2c17386)
- Type error when using actions in templates (#1020) (55956fe), closes #1019
- actions:
*_action and icon_*_action stricly follow what is
allowed in the configuration of this card (see updated documentation).
If you used some hacks, it might break. If those hacks were created to
run javascript code, you can now use action: javascript instead.
- actions: avoid executing invalid actions configurations (#1023) (fe05b52)
- actions: Some of you were using hacks to execute javascript
actions. This release officially implements
action: javascript and
this is the only supported way to execute javascript actions going
forward. Any other configuration might execute the javascript action
while the card is first displayed. Please update your config accordingly
and read the updated documentation.
- actions: Official support for native javascript actions (#1022) (62163cc), closes #1021
- Event propagation to parent would not propagate the event properties (#1017) (a2051d4), closes #1015
- actions: CSS variables
--mdc-ripple-* are no longer supported.
These have been replaced with --button-card-ripple-* variables. You
will need to update your configuration.
- double triggers with icon_*_actions (d9725d7)
- allow html tooltips using the lit html tag (5bb800a)
- console error on click introduced in 5.0.0-dev.1 (fc39748), closes #1001
- color: Card background color will always be
var (--card-background-color) when state is inactive and color_type: card. You can set card background with state.
- color: inactive card background no longer inactive color when
colour_type: card and color set. (#987) (b4f00f9), closes #754
- Embedded light card handle issue (#989) (d01ef37), closes #427 #901
- Hold action on picture entity (#996) (9f2501f), closes #994
- Move while hold on touch devices (#993) (2c17386)
- lock: Option to keep the unlock icon displayed and define custom lock/unlock icon (#966) (3c42b7b), closes #842
- Support to play a sound in the browser on any *_action (#968) (1855013), closes #574
- lock: Lock not displayed on safari/IOS and lock sometimes misplaced (#965) (6c91651), closes #963
- lock: Lock would not display on firefox (#983) (72d2c82), closes #980
- state_display: Allow empty string or null to override state (#976) (0e40cdc), closes #435
- Support to play a sound in the browser on any *_action (#968) (1855013), closes #574
- lock: Lock would not display on firefox (#983) (72d2c82), closes #980
- state_display: Allow empty string or null to override state (#976) (0e40cdc), closes #435
- lock: Option to keep the unlock icon displayed and define custom lock/unlock icon (#966) (3c42b7b), closes #842
- lock: Lock not displayed on safari/IOS and lock sometimes misplaced (#965) (6c91651), closes #963
- Don't trigger action on touchcancel event (#808) (ebbbb31), closes #914
- Fix camera live stream refresh and support aspect ratio & fit mode (#944) (bd9fa97), closes #913
- input_button entity to default to input_button.press for tap_action (#949) (f8e19fd), closes #531 #572
- Replace deprecated --paper-item-icon-color (#925) (8e34b84), closes #924
- Update button-card error display (#958) (921b6eb)
- Support for sections using
section_mode: true (#959) (92dd6d2), closes #854
- Fix camera live stream refresh and support aspect ratio & fit mode (#944) (bd9fa97), closes #913
- input_button entity to default to input_button.press for tap_action (#949) (f8e19fd), closes #531 #572
- Update button-card error display (#958) (921b6eb)
- card would sometimes not be clickable (56c3f44), closes #738 #759
- support for new ha-state-icon in 2024.02 (ab2b393)
- support for new ha-state-icon in 2024.02 (ab2b393)
- color: color wouldn't follow light color with
color: auto (b63f0db), closes #737
- templates: Support for one time evaluation of js templates in
triggers_update and entity (#741) (b372642), closes #618 #558 #368
- Keep default background color for color_type: card when off (41dea3f), closes #737
- lock would not display on many browsers (245441b), closes #740
- remove margin-top on name/label/state introduced with 4.0.0 which broke many cards (53fee75), closes #742 #744
- lock would not display on many browsers (245441b), closes #740
- remove margin-top on name/label/state introduced with 4.0.0 which broke many cards (53fee75), closes #742 #744
- templates: Support for one time evaluation of js templates in
triggers_update and entity (#741) (b372642), closes #618 #558 #368
- Keep default background color for color_type: card when off (41dea3f), closes #737
- color: auto/auto-no-temperature was broken (a63f9a9), closes #737
- helpers: If you were using any of the beta before
4.0.0-dev14. Please replace all the calls to helper functions with helpers.xxx for eg. helpers.relativeTime(entity.state) or helpers.localize(entity)
- hacs: Minimum required HA Version is now 2023.7
- actions: Requires HA 2023.4 minimum. Support for the new action format (
target is also be supported), service_data should be renamed to data (but it still works with the old format)
- icons: This might break your card-mod setup
- this might break some of your color settings
- action:
repeat_limit for hold_action (73c216f), closes #564 #555
- actions: Support for the new action (assist) and all the future ones (d9c17a4), closes #711 #685
- custom_fields: Add
do_not_eval to stop evaluating js templates in an embedded card (1638cf8)
- helpers: all template functions are now available through the
helpers object (f22ed69)
- icons: replace ha-icon with ha-state-icon to follow new HA's icons per domain automatically (ab6a3f5)
- templates: new
relativeTime function to display a relative time in a template and update it automatically (965a3d7), closes #701
- templates: New date and time format helpers (9b4fb05)
- variables: A variable can depend on another variable based on their name's alphabetical order (8cddccb), closes #656
- Force the
numeric_precision for states which are numbers (24d75c2)
- new helper functions for date/time in templates (2b75993), closes #701
- Support for localization in templates (5de2dc9)
- *_action more-info entity as a template was not evaluated (02441b2), closes #734
group_expand now works even if the entity is not a group.xxx (f192ded), closes #645- Color are now aligned with HA > 2022.12 (685d55e), closes #635
- custom fields would sometime throw unsafeHTML errors (c67e1d5), closes #725
- ha-icon (if in custom_fields) size was weird (a448c8e)
- ha-state-icon CSS selector was wrong (a1bb39a)
- icon would be cut with card height defined (19f8393), closes #731
- localization fix (02dfab3), closes #685 #693
- lock icon was displaying over more-info dialog (bf075b0), closes #694
- lock would go out of the button (0b3e4d3)
- non string fiels would error with an unsafeHTML error (d65c347), closes #725
- numerical states would not follow HA's format (72d7c41), closes #662
- optimize contrast color compute (35109c3)
- relativeTime didn't support to set the first letter uppercase (f8b9b09), closes #735
- Some cards with child cards wouldn't be clickable (9f21c58)
- text/icon contrast when using label-card (01e199b)
- variable which were objects were only evaluated once (e40bda9)
- templates:
variables was undefined if none where provided. (fad332b), closes #718
- tooltip would show over everything (1bc8f99)
- color: main config
color was broken (b93c996)
- hacs: minimum HA version 2023.7 (db3b394)
- templates: don't use the
numeric_precision from the card config for localize in js templates by default (2cc384f)
- variable which were objects were only evaluated once (e40bda9)
- custom_fields: Add
do_not_eval to stop evaluating js templates in an embedded card (1638cf8)
- relativeTime didn't support to set the first letter uppercase (f8b9b09), closes #735
- variables: A variable can depend on another variable based on their name's alphabetical order (8cddccb), closes #656
- *_action more-info entity as a template was not evaluated (02441b2), closes #734
- templates: New date and time format helpers (9b4fb05)
- helpers: If you were using any of the beta before
4.0.0-dev14. Please replace all the calls to helper functions with helpers.xxx for eg. helpers.relativeTime(entity.state) or helpers.localize(entity)
- helpers: all template functions are now available through the
helpers object (f22ed69)
group_expand now works even if the entity is not a group.xxx (f192ded), closes #645
- templates:
variables was undefined if none where provided. (fad332b), closes #718
- icon would be cut with card height defined (19f8393), closes #731
- templates: new
relativeTime function to display a relative time in a template and update it automatically (965a3d7), closes #701
- ha-state-icon CSS selector was wrong (a1bb39a)
- tooltip would show over everything (1bc8f99)
- templates: don't use the
numeric_precision from the card config for localize in js templates by default (2cc384f)
- color: main config
color was broken (b93c996)
- numerical states would not follow HA's format (72d7c41), closes #662
- Force the
numeric_precision for states which are numbers (24d75c2)
- action:
repeat_limit for hold_action (73c216f), closes #564 #555
- new helper functions for date/time in templates (2b75993), closes #701
- ha-icon (if in custom_fields) size was weird (a448c8e)
- non string fiels would error with an unsafeHTML error (d65c347), closes #725
- hacs: Minimum required HA Version is now 2023.7
- Support for localization in templates (5de2dc9)
- custom fields would sometime throw unsafeHTML errors (c67e1d5), closes #725
- hacs: minimum HA version 2023.7 (db3b394)
- optimize contrast color compute (35109c3)
- Some cards with child cards wouldn't be clickable (9f21c58)
- text/icon contrast when using label-card (01e199b)
- actions: Requires HA 2023.4 minimum. Support for the new action format (
target is also be supported), service_data should be renamed to data (but it still works with the old format)
- actions: Support for the new action (assist) and all the future ones (d9c17a4), closes #711 #685
- icons: This might break your card-mod setup
- icons: replace ha-icon with ha-state-icon to follow new HA's icons per domain automatically (ab6a3f5)
- this might break some of your color settings
- state_display: Support for
state_display in state (440dc77), closes #426
- card broken with HA 2023.04bXX (9b4f1e2), closes #669 #671
- extra space at bottom because of button-card-action-handler (699b57d), closes #672
- remove border from blank card (b05c6b4), closes #652
- card broken with HA 2023.04bXX (9b4f1e2), closes #669 #671
- extra space at bottom because of button-card-action-handler (699b57d), closes #672
- remove border from blank card (b05c6b4), closes #652
- state_display: Support for
state_display in state (440dc77), closes #426