Expander Card for HomeAssistant

Expander/Collapsible card for HomeAssistant

Introduction

First a few words to start with. A big thank you goes to @Alia5, who initially launched the card. I forked this card for my own HomeAssistant to make a few improvements. I give no guarantee for the functionality and no promise of lifelong maintenance, as I do the whole thing in my free time. Of course, I am happy about every contribution and PR

Demo

Expand button as overlay:

You can even nest expanders!

Clear Background (default theme):

Options

All options are available for editing in Graphical config editor. Title card config is in YAML at this time.

Yaml Options:

Name	Type	Default	Supported options	Description
type	string	Required	`custom:expander-card`	Type of the card.
title	string	Empty	*	Title (Not displayed if using Title-Card)
icon	string	mdi:chevron-down	mdi icon shortcut	Icon in button
expanded	boolean	false	true\|false	Start expanded
animation	boolean	true	true\|false	Should the opening/closing of expander be animated?
min-width-expanded	number	0	number	Min screen width (px) to be expanded on start (use with start expanded above)
max-width-expanded	number	0	number	Max screen width (px) to be expanded on start (use with start expanded above)
storage-id	string	optional	*	Save last expander state in local browser storage
expander-card-id	string	optional	*	An id to use with Set state via action
arrow-color	string	primary-text-color,#fff	css-color	Color of ico expand button
icon-rotate-degree	string	180deg	css-rotate	Changing the degrees of the button icon when clicked
header-color	string	primary-text-color,#fff	css-color	Color of expand button
button-background	string	transparent	css-color	Background color of expand button
expander-card-background	string	ha-card-background, card-background-color,#fff	css-color	Expander Card Background
expander-card-background-expanded	string	Empty	css-color	Expander Card Background when card is opened/expanded
expander-card-display	string	block	css-display	Layout/Display of the card
clear	boolean	false	true\|false	Remove Background, border
gap	string	0.0em	css-size	gap between cards when expander closed. This option depends on your CSS layout: You might need to use `expander-card-display: grid` for this.
padding	string	1em	css-size	padding of all card content
expanded-gap	string	0.6em	css-size	gap between child cards when expander open
child-padding	string	0.0em	css-size	padding of child cards
child-margin-top	string	0.0em	css-size	Margin top of child cards
clear-children	boolean	false	true\|false	Remove Background, border from childs
title-card	object	optional	LovelaceCardConfig	Replace Title with card
title-card-clickable	boolean	false	true\|false	Should the complete diff clickable?
title-card-button-overlay	boolean	false	true\|false	Overlay expand button over title-card
overlay-margin	string	0.0em	css-size	Margin from top right of expander button (if overlay)
title-card-padding	string	0px	css-size	padding of title-card
show-button-users	object[]	optional	*	Choose the persons/users that button is visible to them.
start-expanded-users	object[]	optional	*	Choose the persons/users that card will be start expanded for them.
cards	object[]	optional	LovelaceCardConfig[]	Child cards to show when expanded
style	string	optional.	css style rules	Advanced css styling rules

Examples

Here are a few examples of usage.

Title card

Example title card that is clickable and has 2 nested cards, which is directly expanded

    - type: custom:expander-card
      child-margin-top: 0.6em
      padding: 0
      clear: true
      title-card-button-overlay: true
      title-card-clickable: true
      expanded: true
      title-card:
        type: "custom:digital-clock"
        dateFormat:
          weekday: "long"
          day: "2-digit"
          month: "short"
        timeFormat:
          hour: "2-digit"
          minute: "2-digit"
      cards:
        - type: custom:simple-weather-card
          entity: weather.openweathermap
          primary_info:
            - wind_speed
            - wind_bearing
          secondary_info:
            - precipitation
            - precipitation_probability
        - type: custom:hourly-weather
          entity: weather.openweathermap
          icons: true
          show_precipitation_probability: true
          show_precipitation_amounts: true
          forecast_type: "hourly"
          num_segments: 10"
          label_spacing: "1"
          name: null
          show_wind: speed

Heading Title card

Example with heading title card to the possiblity to style your title.

      - type: custom:expander-card
        title-card:
          type: heading
          heading: Title
          heading_style: title
          badges:
            - type: entity
              show_name: false
              show_state: true
              show_icon: true
              entity: light.bed_light
          icon: mdi:account

Template Title card with Mushroom

If you need templates in your title, you can make good use of the Mushroom cards. Here's an example using the Mushroom title card. https:

      - type: custom:expander-card
        title-card:
          type: custom:mushroom-title-card
          title: |-
            {{ now().hour }}

Simple Title

Example with title that is clickable and has 2 nested cards.

      - type: custom:expander-card
        child-margin-top: 0.6em
        padding: 0
        title: "Test"
        title-card-button-overlay: true
        title-card-clickable: true
        cards:
          - type: custom:simple-weather-card
            entity: weather.openweathermap
            primary_info:
              - wind_speed
              - wind_bearing
            secondary_info:
              - precipitation
              - precipitation_probability
          - type: custom:hourly-weather
            entity: weather.openweathermap
            icons: true
            show_precipitation_probability: true
            show_precipitation_amounts: true
            forecast_type: "hourly"
            num_segments: 10"
            label_spacing: "1"
            name: null
            show_wind: speed

Title with min-width-expanded

Example with title that is clickable and has 2 nested cards with are automatically expanded when the screen is more than 300px.

      - type: custom:expander-card
        child-margin-top: 0.6em
        padding: 0
        title: "Test"
        title-card-button-overlay: true
        title-card-clickable: true
        min-width-expanded: 300
        cards:
          - type: custom:simple-weather-card
            entity: weather.openweathermap
            primary_info:
              - wind_speed
              - wind_bearing
            secondary_info:
              - precipitation
              - precipitation_probability
            name: in Gärtringen
          - type: custom:hourly-weather
            entity: weather.openweathermap
            icons: true
            show_precipitation_probability: true
            show_precipitation_amounts: true
            forecast_type: "hourly"
            num_segments: 10"
            label_spacing: "1"
            show_wind: speed

Title card with action

The configuration below will open or close the expander when you tap the Mushroom Light Card. This means you cannot switch the light on or off by tapping it, but you can still adjust the brightness.

    type: custom:expander-card
    title: Expander Card
    expander-card-id: my-light-card
    cards:
      - type: entities
        entities:
          - entity: sun.sun
    title-card:
      type: tile
      entity: light.bed_light
      vertical: false
      features_position: inline
      features:
        - type: light-brightness
      tap_action:
        action: fire-dom-event
        expander-card:
          data:
            expander-card-id: my-light-card
            action: toggle

Set state via action

You can set the state of expander card(s) using the fire-dom-event action on any card that supports actions.

Set expander card(s) to have expander-card-id. Multiple expander cards can shared the same id if you wish to set their state together.
Set action on another card using the fire-dom-event action.

 tap_action:
   action: fire-dom-event
   expander-card:
     data:
       expander-card-id: <expander-card-id>
       action: < open | close | toggle >

Example

Expander card config

    - type: custom:expander-card
      expander-card-id: my-expander-card

Action on another card

show_name: true
show_icon: true
type: button
name: Expand my-expander-card
icon: mdi:chevron-down
tap_action:
  action: fire-dom-event
  expander-card:
    data:
      expander-card-id: my-expander-card
      action: open

Style

You can do advanced styling using the style configuration parameter. Classes available are per the images below.

State

For all elements shown, the class open will be added when the Expander card is open, and closed added when the Expander is closed.

Animation

When Expander card animation is enabled, for all elements except those listed below, the class opening will be added when the expander is in the process of opening and the class closing will be added when the expander is in the process of closing. When not opening or closing, the class idle will be added. The class animation will also be added. You may wish to use these classes for transition affects. Expander card uses 0.35s ease for transitions. See the final example below for transitioning title font size and color.

NOTE: .outer-container for Title card will not have animation or opening/closing applied.

Special considerations

.children-wrapper is used for opening/closing animation and hiding children cards. You should not style this element. It is shown for completeness.
margin-bottom on each children card's .outer-container is used to transition cards sliding down and up while animating. Do not style margin-bottom and if altering any transitions, extend the included transition style for opening and closing.
As much as possible, use class selector combinations to get your styles to a higher specificity. e.g. .expander-card.animation.open is more specific than any built in classes so if you use that selector, you as less likely to need to use !important.
For animation, during opening, the classes will be open and opening. During closing, classes will be open and closing until the close sequence has ended after which the classes will be close and idle.
If you are considering any transition affects, check those already applied and extend those with any styling you add.

Styling Examples

Using an example to set the background based on the status. As background color is a transition element, you need to style both open & opening and close and closing to get the background to transition during opening/closing. Otherwise the transition will take place after the expander has opened/closed.

style: |-
  .expander-card.animation.open,
  .expander-card.animation.opening {
    background-color: red;
  }
  .expander-card.animation.close,
  .expander-card.animation.closing {
    background-color: #C8A2C8;
  }

Only the background of the button. Here !important is needed to override the hover ripple.

style: |
  .header.animation.open,
  .header.animation.opening {
    background-color: red !important;
  }
  .header.animation.close,
  .header.animation.closing {
    background-color: #C8A2C8 !important;
  }

Switching the arrow from right to left, with reduced horizontal padding of the button.

style: |
  .header {
    flex-direction: row-reverse !important;
    padding: 0.8em 0 !important;
  }

If you have a title-card

style: |
.title-card-header {
  flex-direction: row-reverse !important;
  padding: 0.8em 0 !important;
}

Transitioning the title font size and color. Here the !important on close/closing is to make sure that the font size and color both change on closing as open will still be added until fully closed at which stage close will be added and open removed.

style: |
  .header > .title {
    transition: color 0.35s ease, font-size 0.35s ease;
  }
  .header.animation.close > .title, 
  .header.animation.closing > .title
  {
    color: green !important;
    font-size: var(--ha-font-size-l) !important;
  }
  .header.animation.open > .title,
  .header.animation.opening > .title
  {
    color: red;
    font-size: var(--ha-font-size-m);
  }

Change the title size

    style: |
      .title {
        font-size: var(--ha-font-size-l);
      }

Card Mod

Before the style attribute, card mod was used to style the card. Although card-mod still works, it is better to switch everything to use the style attribute. Please do not open issue(s) when card mod is not working.

Installation

HACS

Expander-Card is available in HACS (Home Assistant Community Store) by default.

Install HACS if you don't have it already
Open HACS in Home Assistant
Searching for expander card

Manual

Download expander-card.js file from the latest release.
Put expander-card.js file into your config/www folder.
Add reference to expander-card.js in Dashboard. There's two way to do that:
- Using UI: Settings → Dashboards → More Options icon → Resources → Add Resource → Set Url as /local/expander-card.js → Set Resource type as JavaScript Module. Note: If you do not see the Resources menu, you will need to enable Advanced Mode in your User Profile
- Using YAML: Add following code to lovelace section.
```
  resources:
      - url: /local/expander-card.js
        type: module
```

FAQ

Issue after upgrade to HA 2025.6

There is/was an issue after upgrading to HA 2025.6 (maybe with newer version is not valid anymore) See forum and issue a) For the view type sections cards is not working anymore. You have to rename it to sections.

Before

views:
 - title: MyView
   path: my-view
   cards: ...

Now

views:
 - title: MyView
   path: my-view
   sections: ...

Option Gap is not working

If this option doesn't work, check your browser's console output. Your current CSS layout might not support this option. You can use the expander-card-display: grid option to set a layout that supports this option.

Support

Clone and create a PR to help make the card even better.

Please ⭐️ or sponsor this repo when you like it.

Name		Name	Last commit message	Last commit date
Latest commit History 1,139 Commits
.github		.github
docs/images		docs/images
examples		examples
src		src
.gitignore		.gitignore
.npmrc		.npmrc
README.md		README.md
eslint.config.mjs		eslint.config.mjs
hacs.json		hacs.json
license.txt		license.txt
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
rollup.config.mjs		rollup.config.mjs
svelte.config.js		svelte.config.js
tsconfig.json		tsconfig.json
vite.config.js		vite.config.js

Uh oh!

License

MelleD/lovelace-expander-card

Folders and files

Latest commit

History

Repository files navigation

Expander Card for HomeAssistant

Introduction

Demo

Options

Examples

Title card

Heading Title card

Template Title card with Mushroom

Simple Title

Title with min-width-expanded

Title card with action

Set state via action

Expander card config

Action on another card

Style

State

Animation

Special considerations

Styling Examples

Card Mod

Installation

HACS

Manual

FAQ

Issue after upgrade to HA 2025.6

Option Gap is not working

Support

Sponsor ❤️

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 85

Sponsor this project

Uh oh!

Packages 0

Uh oh!

Languages

Packages