Changelog
7.0.1 (2025-11-13)Bug Fixes
Bug Fixes
7.0.0 (2025-11-10)⚠ BREAKING CHANGES
spin (to make the icon/entity_picture rotate) has
been renamed to rotate, please update your configurationstriggers_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; ]]]'
Features
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 )
Bug Fixes
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 )
Documentation
Features
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
Bug Fixes
variables: Fixed a type error when a variable is null (#1110 ) (05f1631 ), closes #1109
Documentation
Bug Fixes
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 )
Features
custom_fields: New force_recreate: true to recreate the nested card on each config update (#1102 ) (0a85dff ), closes #1086
Bug Fixes
variables: storing objects or functions in variables would fail in specific cases (#1103 ) (4778c4a )
⚠ BREAKING CHANGES
spin (to make the icon/entity_picture rotate) has
been renamed to rotate, please update your configurations
Features
Bug Fixes
⚠ BREAKING CHANGES
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; ]]]'
Features
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 )
Documentation
Features
triggers_update is not required anymore, all entities used in JS templates are now discovered automatically. (#1080 ) (ccb5766 ), closes #1074
Documentation
Fix action config table format (f65b2a6 )
Features
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 )
Documentation
Fix toast action table formating (af8c932 )
Remove uneeded - from code examples (b202a09 )
6.0.0 (2025-10-24)⚠ BREAKING CHANGES
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.
Features
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
Bug Fixes
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
Documentation
New documentation website replacing the current README (#1073 ) (2de1890 )
Features
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
⚠ BREAKING CHANGES
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.
Features
Bug Fixes
Features
Support templates for hidden to hide the card completely (#1013 ) (263d366 ), closes #1004
Bug Fixes
custom_fields cards are not recreated from scratch anymore if their config is modified (#1064 ) (2d8aaa4 ), closes #1060
Features
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 )
Features
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 )
Features
actions: confirmation support for javascript, PIN & Password confirmation support (#1033 ) (6632114 ), closes #1030
Bug Fixes
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
5.0.2 (2025-10-06)Bug Fixes
actions: complex templates would break in specific cases (#1029 ) (854b96a ), closes #1028
5.0.1 (2025-10-05)Bug Fixes
5.0.0 (2025-10-05)⚠ BREAKING CHANGES
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.
Features
Bug Fixes
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
⚠ BREAKING CHANGES
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.
Bug Fixes
actions: avoid executing invalid actions configurations (#1023 ) (fe05b52 )
⚠ BREAKING CHANGES
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.
Features
actions: Official support for native javascript actions (#1022 ) (62163cc ), closes #1021
Bug Fixes
Features
Bug Fixes
Event propagation to parent would not propagate the event properties (#1017 ) (a2051d4 ), closes #1015
⚠ BREAKING CHANGES
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.
Features
Bug Fixes
double triggers with icon_*_actions (d9725d7 )
Features
allow html tooltips using the lit html tag (5bb800a )
Bug Fixes
console error on click introduced in 5.0.0-dev.1 (fc39748 ), closes #1001
⚠ BREAKING CHANGES
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.
Features
Bug Fixes
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 )
4.3.0 (2025-08-31)Features
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
Bug Fixes
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
Features
Support to play a sound in the browser on any *_action (#968 ) (1855013 ), closes #574
Bug Fixes
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
Features
lock: Option to keep the unlock icon displayed and define custom lock/unlock icon (#966 ) (3c42b7b ), closes #842
Bug Fixes
lock: Lock not displayed on safari/IOS and lock sometimes misplaced (#965 ) (6c91651 ), closes #963
4.2.0 (2025-08-28)Features
Bug Fixes
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 )
Documentation
Features
Support for sections using section_mode: true (#959 ) (92dd6d2 ), closes #854
Features
Bug Fixes
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 )
Documentation
Bug Fixes
4.1.2 (2024-02-01)Bug Fixes
card would sometimes not be clickable (56c3f44 ), closes #738 #759
support for new ha-state-icon in 2024.02 (ab2b393 )
Bug Fixes
support for new ha-state-icon in 2024.02 (ab2b393 )
Bug Fixes
4.1.1 (2023-08-03)Bug Fixes
color: color wouldn't follow light color with color: auto (b63f0db ), closes #737
4.1.0 (2023-08-03)Features
templates: Support for one time evaluation of js templates in triggers_update and entity (#741 ) (b372642 ), closes #618 #558 #368
Bug Fixes
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
Bug Fixes
lock would not display on many browsers (245441b ), closes #740
Bug Fixes
remove margin-top on name/label/state introduced with 4.0.0 which broke many cards (53fee75 ), closes #742 #744
Features
templates: Support for one time evaluation of js templates in triggers_update and entity (#741 ) (b372642 ), closes #618 #558 #368
Bug Fixes
Keep default background color for color_type: card when off (41dea3f ), closes #737
4.0.1 (2023-07-30)Bug Fixes
color: auto/auto-no-temperature was broken (a63f9a9 ), closes #737
4.0.0 (2023-07-29)⚠ BREAKING CHANGES
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.7actions: 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 setupthis might break some of your color settings
Features
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 )
Bug Fixes
*_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 )
Bug Fixes
variable which were objects were only evaluated once (e40bda9 )
Features
custom_fields: Add do_not_eval to stop evaluating js templates in an embedded card (1638cf8 )
Bug Fixes
relativeTime didn't support to set the first letter uppercase (f8b9b09 ), closes #735
Features
variables: A variable can depend on another variable based on their name's alphabetical order (8cddccb ), closes #656
Bug Fixes
*_action more-info entity as a template was not evaluated (02441b2 ), closes #734
Features
templates: New date and time format helpers (9b4fb05 )
⚠ BREAKING CHANGES
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)
Features
helpers: all template functions are now available through the helpers object (f22ed69 )
Bug Fixes
group_expand now works even if the entity is not a group.xxx (f192ded ), closes #645
Bug Fixes
templates: variables was undefined if none where provided. (fad332b ), closes #718
Bug Fixes
icon would be cut with card height defined (19f8393 ), closes #731
Features
templates: new relativeTime function to display a relative time in a template and update it automatically (965a3d7 ), closes #701
Bug Fixes
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 )
Bug Fixes
color: main config color was broken (b93c996 )
Bug Fixes
numerical states would not follow HA's format (72d7c41 ), closes #662
Features
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
Bug Fixes
ha-icon (if in custom_fields) size was weird (a448c8e )
Bug Fixes
non string fiels would error with an unsafeHTML error (d65c347 ), closes #725
⚠ BREAKING CHANGES
hacs: Minimum required HA Version is now 2023.7
Features
Support for localization in templates (5de2dc9 )
Bug Fixes
custom fields would sometime throw unsafeHTML errors (c67e1d5 ), closes #725
hacs: minimum HA version 2023.7 (db3b394 )
Bug Fixes
optimize contrast color compute (35109c3 )
Some cards with child cards wouldn't be clickable (9f21c58 )
Bug Fixes
text/icon contrast when using label-card (01e199b )
⚠ BREAKING CHANGES
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)
Features
actions: Support for the new action (assist) and all the future ones (d9c17a4 ), closes #711 #685
⚠ BREAKING CHANGES
icons: This might break your card-mod setup
Features
icons: replace ha-icon with ha-state-icon to follow new HA's icons per domain automatically (ab6a3f5 )
⚠ BREAKING CHANGES
this might break some of your color settings
Bug Fixes
3.5.0 (2023-04-02)Features
state_display: Support for state_display in state (440dc77 ), closes #426
Bug Fixes
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
Documentation
Bug Fixes
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
Documentation
Features
state_display: Support for state_display in state (440dc77 ), closes #426
3.4.2 (2021-02-17)Bug Fixes