Expander Card

https://melled.github.io/lovelace-expander-card
Admin
Expander Card is a highly configurable Lovelace card for Home Assistant that allows you to organize...
Tokens:9,493
Snippets:123
Trust Score:9.7
Update:5 months ago
Show doc for...
Tokens:
Raw
### Serve Documentation

Source: https://melled.github.io/lovelace-expander-card/chapter/contribution/contribution

Start a local server to view documentation updates in real-time.

```bash
# start server to see updates in realtime
zensical serve

```

--------------------------------

### Install Dependencies

Source: https://melled.github.io/lovelace-expander-card/chapter/contribution/contribution

Install project dependencies using npm or pnpm.

```bash
# Install dependencies
npm install
# or
pnpm install

```

--------------------------------

### Start Development Server

Source: https://melled.github.io/lovelace-expander-card/chapter/contribution/contribution

Run the development server to test your changes locally.

```bash
# Start development server
npm run srv

```

--------------------------------

### Expander Card Configuration Example

Source: https://melled.github.io/lovelace-expander-card/chapter/templating/action

Example configuration for a custom expander card, including its unique ID.

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

```

--------------------------------

### String Style Format Example

Source: https://melled.github.io/lovelace-expander-card/chapter/style/styling-examples

Demonstrates the traditional string format for applying CSS rules to the expander card. Use this for simple, single-rule styles.

```yaml
type: custom:expander-card
title: String Style Example
style: |
  .expander-card {
    background-color: red;
    padding: 1em;
  }
cards:
  - type: entity
    entity: light.living_room

```

--------------------------------

### Title Card Example with Nested Cards

Source: https://melled.github.io/lovelace-expander-card/chapter/configuration/examples

This example demonstrates a title card for a room, integrating Mushroom Cards, Vertical Stack-in Card, and card-mod for styling. It's designed to be directly expanded and includes weather chips.

```yaml
- 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:vertical-stack-in-card
    cards:
      # --- TOP ROW ---
      - type: horizontal-stack
        cards:

          - type: custom:mushroom-template-card
            primary: Living Room
            icon: mdi:sofa
            layout: vertical
            card_mod:
              style:
                mushroom-shape-icon$: |
                  .shape {
                    background: none !important;
                    --shape-color: transparent !important;
                  }
                .: |
                  ha-card {
                    background: none !important;
                    border: none !important;
                    box-shadow: none !important;
                    /* This moves the entire card (icon + text) up by 6px */
                    margin-top: -15px !important; 
                  }
                  mushroom-state-info {
                    margin-top: -25px !important; /* Keeps the tight text-to-icon gap */
                  }
                  mushroom-state-item {
                    gap: 0px !important;
                  }
                  :host {
                    --mush-icon-size: 70px;
                    --primary-text-color: white;
                    --primary-font-weight: 660;
                  }

          - type: custom:mushroom-light-card
            entity: light.fibaro_dimmer_2_living_room_spotlight
            name: Lights
            card_mod:
              style: |
                ha-card {
                  background: none !important;
                  border: none !important;
                  box-shadow: none !important;
                  /* Reduced from 35px to 18px */
                  margin-top: 8px !important; 
                  /* Ensures the card doesn't cut off the text */
                  width: 100% !important;
                }

      # --- BOTTOM ROW (Chips) ---
      - type: custom:mushroom-chips-card
        alignment: center
        chips:
          - type: template
            icon: mdi:thermometer
            icon_color: orange
            content: "21.71 °C"
            card_mod:
              style: |
                ha-card {
                  box-shadow: none !important;
                  border: none !important;
                }
          - type: template
            icon: mdi:water-percent
            icon_color: blue
            content: "44.89 %"
            card_mod:
              style: |
                ha-card {
                  box-shadow: none !important;
                  border: none !important;
                }
          - type: template
            icon: mdi:gauge
            icon_color: red
            content: "974.3 hPa"
            card_mod:
              style: |
                ha-card {
                  box-shadow: none !important;
                  border: none !important;
                }
          - type: template
            icon: mdi:flash
            icon_color: yellow
            content: "357 W"
            card_mod:
              style: |
                ha-card {
                  box-shadow: none !important;
                  border: none !important;
                }

```

--------------------------------

### Template with Variables and Styles

Source: https://melled.github.io/lovelace-expander-card/chapter/templating/template

This example demonstrates using variables and applying conditional styling based on those variables. The nullish coalescing operator (??) is useful for handling undefined variables.

```yaml
variables:
  - variable: weather_warnings
    value_template: |
      [[[
        return is_state('input_boolean.weather_warnings', 'on');
      ]]]
templates:
  - template: expanded
    value_template: |
       [[[
         return variables.weather_warnings ?? false;
       ]]]
  - template: style
    value_template: |
      [[[
        return `
          .title 
          { 
            transition: color 0.35s ease, font-weight 0.35s ease;
            color: ${variables.weather_warnings ? 'red' : 'var(--primary-text-color)'};
            font-weight: ${variables.weather_warnings ? '700' : 'var(--ha-font-weight-body)'};
          }`;
      ]]]
```

--------------------------------

### Button Card to Control Expander Card

Source: https://melled.github.io/lovelace-expander-card/chapter/templating/action

Example of a button card configured to trigger an action on a specific expander card. This button will open the 'my-expander-card'.

```yaml
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

```

--------------------------------

### Button Background Only (Object Format)

Source: https://melled.github.io/lovelace-expander-card/chapter/style/styling-examples

Achieves the same button background styling as the string format example but uses the structured object format for CSS properties.

```yaml
type: custom:expander-card
title: Button Background (Object Format)
style:
  .header.animation.open, .header.animation.opening:
    background-color: red !important
  .header.animation.close, .header.animation.closing:
    background-color: '#C8A2C8 !important'
cards:
  - type: entity
    entity: light.bedroom

```

--------------------------------

### Complex Styling with Object Format and Animations

Source: https://melled.github.io/lovelace-expander-card/chapter/style/styling-examples

Demonstrates advanced styling using the object format for selectors and properties, including background color and title transitions for open/closed states. This example also customizes the arrow color.

```yaml
type: custom:expander-card
title: Complex Styling Example
style:
  .expander-card.animation.open, .expander-card.animation.opening:
    - background-color: '#1e3a8a'
    - transition: background-color 0.35s ease
  .expander-card.animation.close, .expander-card.animation.closing:
    - background-color: '#047857'
    - transition: background-color 0.35s ease
  .header > .title:
    - font-size: var(--ha-font-size-l)
    - color: '#ffffff'
    - font-weight: bold
    - transition: color 0.35s ease, font-size 0.35s ease
  .header.animation.open > .title, .header.animation.opening > .title:
    - color: '#fbbf24'
    - font-size: var(--ha-font-size-xl)
  .header.animation.close > .title, .header.animation.closing > .title:
    - color: '#ffffff'
    - font-size: var(--ha-font-size-l)
  .arrow:
    - color: '#fbbf24'
cards:
  - type: entity
    entity: light.living_room

```

--------------------------------

### Object Style Format Example

Source: https://melled.github.io/lovelace-expander-card/chapter/style/styling-examples

Illustrates the structured object format for defining CSS styles, which can be more readable for complex styles. Keys are selectors, and values are arrays of property strings.

```yaml
type: custom:expander-card
title: Object Style Example
style:
  .expander-card:
    - background-color: red
    - padding: 1em
  .header > .title:
    - font-size: var(--ha-font-size-l)
    - color: green
cards:
  - type: entity
    entity: light.living_room

```

--------------------------------

### Clickable Title Card with Digital Clock and Weather

Source: https://melled.github.io/lovelace-expander-card/chapter/configuration/examples

This example shows a clickable title card that expands to reveal weather information. The title card itself is a custom digital clock.

```yaml
- 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

```

--------------------------------

### Template Returning Structured Object for Styling

Source: https://melled.github.io/lovelace-expander-card/chapter/style/style

Templates can dynamically generate styling objects. This example shows how to return an object with multiple selectors and properties, including `!important`.

```javascript
templates:
  - template: style
    value_template: |-
      [[[
        return { 
          '.expander-card': [
            'background-color: red !important',
            'padding: 1em'
          ],
          '.header > .title': [
            { 'color': 'white' },
            { 'font-size': 'var(--ha-font-size-l)' }
          ]
        }
      ]]]

```

--------------------------------

### Define Javascript Variable for State

Source: https://melled.github.io/lovelace-expander-card/chapter/templating/template

Example of defining a variable that tracks the state of a Home Assistant entity. Ensure your templates handle the initial `undefined` state of variables.

```yaml
variables:
  - variable: weather_warnings
    value_template: |
      [[[
        return is_state('input_boolean.weather_warnings', 'on');
      ]]]

```

--------------------------------

### Mushroom Title Card with Templating

Source: https://melled.github.io/lovelace-expander-card/chapter/configuration/examples

Integrate Mushroom title cards for dynamic titles using templates. The example uses a Jinja2 template to display the current hour.

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


```

--------------------------------

### Expand on Minimum Width with Clickable Title

Source: https://melled.github.io/lovelace-expander-card/chapter/configuration/examples

Set a minimum screen width for expanded view with a clickable title. This example includes two nested weather cards and specifies `min-width-expanded`.

```yaml
- 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


```

--------------------------------

### Build Documentation

Source: https://melled.github.io/lovelace-expander-card/chapter/contribution/contribution

Build the project documentation, cleaning previous builds.

```bash
# build docs
zensical build --clean

```

--------------------------------

### Build for Production

Source: https://melled.github.io/lovelace-expander-card/chapter/contribution/contribution

Build the project for production deployment.

```bash
# Build for production
npm run build

```

--------------------------------

### Navigate to Docs Directory

Source: https://melled.github.io/lovelace-expander-card/chapter/contribution/contribution

Change the current directory to the 'docs' folder.

```bash
# cd docs
cd docs

```

--------------------------------

### Run Linting

Source: https://melled.github.io/lovelace-expander-card/chapter/contribution/contribution

Check code quality and style using ESLint.

```bash
# Run es linting
npm run lint

```

--------------------------------

### Clone Repository

Source: https://melled.github.io/lovelace-expander-card/chapter/contribution/contribution

Clone your forked repository to your local machine to begin making changes.

```bash
# Fork via GitHub UI, then clone your fork
git clone https://github.com/YOUR_USERNAME/lovelace-expander-card.git
cd lovelace-expander-card

```

--------------------------------

### Commit Changes

Source: https://melled.github.io/lovelace-expander-card/chapter/contribution/contribution

Stage and commit your changes with a clear, descriptive message.

```bash
git add .
git commit -m 'Add some AmazingFeature'

```

--------------------------------

### Add Expander Card Resource via YAML

Source: https://melled.github.io/lovelace-expander-card/quick-start

Add this configuration to your `lovelace` section in `configuration.yaml` to include the Expander Card as a module.

```yaml
resources:
  - url: /local/expander-card.js
    type: module
```

--------------------------------

### Push to Fork

Source: https://melled.github.io/lovelace-expander-card/chapter/contribution/contribution

Push your committed changes to your fork on GitHub.

```bash
git push origin feature/AmazingFeature

```

--------------------------------

### Expander Card Action Configuration

Source: https://melled.github.io/lovelace-expander-card/chapter/templating/action

Configure the `fire-dom-event` action to control expander cards. Specify the expander card ID and the desired action (open, close, toggle).

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

```

--------------------------------

### Troubleshoot Expander Card Option Gap

Source: https://melled.github.io/lovelace-expander-card/chapter/faq/faq

If the 'expander-card-display: grid' option is not working, check your browser's console for CSS layout errors. Ensure your current CSS supports this option or use 'expander-card-display: grid' to enforce a compatible layout.

```yaml
expander-card-display: grid
```

--------------------------------

### String Format for CSS Styling

Source: https://melled.github.io/lovelace-expander-card/chapter/style/style

Use this format to apply CSS rules directly as a string. It's suitable for simple or complex styling needs.

```yaml
style: |
  .expander-card {
    background-color: red;
  }

```

--------------------------------

### Create Feature Branch

Source: https://melled.github.io/lovelace-expander-card/chapter/contribution/contribution

Create a new branch for your feature or bug fix before making changes.

```bash
git checkout -b feature/AmazingFeature
# or
git checkout -b fix/BugFix

```

--------------------------------

### Animated Background Based on State

Source: https://melled.github.io/lovelace-expander-card/chapter/style/styling-examples

Applies animated background colors based on the expansion state (open/closed) using transitions. Ensure both open/opening and close/closing states are styled for smooth transitions.

```yaml
type: custom:expander-card
title: Animated Background
style: |-
  .expander-card.animation.open,
  .expander-card.animation.opening {
    background-color: red;
  }
  .expander-card.animation.close,
  .expander-card.animation.closing {
    background-color: #C8A2C8;
  }
cards:
  - type: entity
    entity: light.living_room

```

--------------------------------

### Object Format for CSS Styling

Source: https://melled.github.io/lovelace-expander-card/chapter/style/style

Apply CSS rules using a structured object. This format uses CSS selectors as keys and arrays of property-value pairs as values, offering more organization.

```yaml
style:
  .expander-card:
    - background-color: red

```

--------------------------------

### Expander Card with Actionable Title Card

Source: https://melled.github.io/lovelace-expander-card/chapter/configuration/examples

Configure an expander card where the title card (a Mushroom tile card) triggers the expander's toggle action. Note that tapping the title card will not control the light directly.

```yaml
    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


```

--------------------------------

### Fix Linting Errors

Source: https://melled.github.io/lovelace-expander-card/chapter/contribution/contribution

Automatically fix common linting errors.

```bash
# Fix es linting
npm run lint-fix

```

--------------------------------

### Template for Expanded State

Source: https://melled.github.io/lovelace-expander-card/chapter/templating/template

Use this template to track the expanded state of an `input_boolean`. Ensure the javascript is correctly enclosed in `[[[]]]`.

```yaml
templates:
  - template: expanded
    value_template: |
       [[[
         return is_state('input_boolean.weather_warnings', 'on');
       ]]]
```

--------------------------------

### Update HA 2025.6 Card Configuration

Source: https://melled.github.io/lovelace-expander-card/chapter/faq/faq

After upgrading to Home Assistant 2025.6, the 'cards' key in view configurations is no longer supported. Rename it to 'sections' to ensure your views render correctly.

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

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

```

--------------------------------

### Master Expander Card Configuration

Source: https://melled.github.io/lovelace-expander-card/chapter/templating/template

This is a master expander card configuration that sets an `expander-card-id`. This ID is used to broadcast its open state to other expander cards.

```yaml
type: custom:expander-card
title: Expander Card - Master
expander-card-id: test_expander_id
cards:
  - type: entity
    entity: light.kitchen_lights
```

--------------------------------

### Button Background Only (String Format)

Source: https://melled.github.io/lovelace-expander-card/chapter/style/styling-examples

Styles only the background of the header button during expansion/collapse states. `!important` is used to override default hover effects.

```yaml
type: custom:expander-card
title: Button Background
style: | 
  .header.animation.open, 
  .header.animation.opening {
    background-color: red !important;
  }
  .header.animation.close, 
  .header.animation.closing {
    background-color: #C8A2C8 !important;
  }
cards:
  - type: entity
    entity: light.bedroom

```

--------------------------------

### Clickable Title Card with Nested Cards

Source: https://melled.github.io/lovelace-expander-card/chapter/configuration/examples

Configure a simple clickable title for an expander card containing two nested weather cards. Adjust padding and child margin for layout control.

```yaml
- 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


```

--------------------------------

### Heading Title Card Configuration

Source: https://melled.github.io/lovelace-expander-card/chapter/configuration/examples

Use a 'heading' type title card for styled titles with badges. Ensure the entity for the badge is correctly configured.

```yaml
- 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
```

--------------------------------

### Expander Card Following Master State

Source: https://melled.github.io/lovelace-expander-card/chapter/templating/template

This expander card follows the open state of a master expander card. The master's state is accessed via `variables.<expander-card-id>_open`.

```yaml
type: custom:expander-card
title: Expander Card - Follow
cards:
  - type: entity
    entity: light.bed_light
templates:
  - template: expanded
    value_template: |-
      [[[
        return variables.test_expander_id_open;
      ]]]
```

--------------------------------

### Expander Card Following Opposite State

Source: https://melled.github.io/lovelace-expander-card/chapter/templating/template

This expander card follows the master expander card's state but inverts it. Use the negation operator `!` to achieve the opposite state.

```yaml
type: custom:expander-card
title: Expander Card - Opposite Follow
cards:
  - type: entity
    entity: light.bed_light
templates:
  - template: expanded
    value_template: |-
      [[[
        return !variables.test_expander_id_open;
      ]]]
```

--------------------------------

### Disable Preview Expansion in Expander Card

Source: https://melled.github.io/lovelace-expander-card/chapter/configuration/gui-configuration

Set `preview-expanded: false` in the `expander-card:` key within your dashboard's raw configuration to prevent expander cards from being expanded by default in UI edit/preview mode. This configuration should ideally be placed at the top of your dashboard's raw configuration.

```yaml
expander-card:
  preview-expanded: false
views:
  - title: Home
    # ... other dashboard "Raw configuration"


```

--------------------------------

### Animated Title Font and Color

Source: https://melled.github.io/lovelace-expander-card/chapter/style/styling-examples

Applies transitions to the title's font size and color during expansion and collapse. The `!important` flag ensures styles are applied correctly during closing animations.

```yaml
type: custom:expander-card
title: Dynamic Title
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);
  }
cards:
  - type: entities
    entities:
      - light.kitchen

```

--------------------------------

### Arrow Position - Left Side

Source: https://melled.github.io/lovelace-expander-card/chapter/style/styling-examples

Moves the expansion arrow to the left side of the header and reduces horizontal padding. This modifies the default layout of the header element.

```yaml
type: custom:expander-card
title: Left Arrow
style: | 
  .header {
    flex-direction: row-reverse !important;
    padding: 0.8em 0 !important;
  }
cards:
  - type: entity
    entity: sensor.temperature

```

--------------------------------

### Set Title Card Overlay Height Relative to Title Card

Source: https://melled.github.io/lovelace-expander-card/chapter/style/styling-examples

Control the title card overlay height proportionally to the title card's height using a CSS variable. The `--expander-card-overlay-height` variable is automatically calculated.

```yaml
type: custom:expander-card
title-card:
  type: picture
  image: /local/header.jpg
title-card-overlay: true
style: |
  .header-overlay {
    height: calc(var(--expander-card-overlay-height) * 0.66) !important;
  }
cards:
  - type: entities
    entities:
      - sensor.temperature
      - sensor.humidity

```

--------------------------------

### Arrow Position with Title Card (With Overlay)

Source: https://melled.github.io/lovelace-expander-card/chapter/style/styling-examples

Positions the arrow to the left when a title card with an overlay is enabled. This targets the overlay header element using `.title-card-header-overlay > .header-overlay`.

```yaml
type: custom:expander-card
title-card:
  type: picture
  image: /local/image.jpg
title-card-overlay: true
style: | 
  .title-card-header-overlay > .header-overlay {
    flex-direction: row-reverse !important;
    padding: 0.8em 0 !important;
  }
cards:
  - type: entity
    entity: media_player.living_room

```

--------------------------------

### Match Title Card Overlay to Arrow Height

Source: https://melled.github.io/lovelace-expander-card/chapter/style/styling-examples

Set the title card overlay height to 'unset' to make it match the height of the arrow. This is useful when using a picture as the title card.

```yaml
type: custom:expander-card
title-card:
  type: picture
  image: /local/background.jpg
title-card-overlay: true
style: |
  .header-overlay {
    height: unset !important;
  }
cards:
  - type: weather-forecast
    entity: weather.home

```

--------------------------------

### Change Title Font Size

Source: https://melled.github.io/lovelace-expander-card/chapter/style/styling-examples

Adjust the font size of the card title directly using CSS. This method does not involve animations.

```yaml
type: custom:expander-card
title: Large Title
style: |
  .title {
    font-size: var(--ha-font-size-l);
  }
cards:
  - type: entity
    entity: climate.thermostat

```

--------------------------------

### Arrow Position with Title Card (No Overlay)

Source: https://melled.github.io/lovelace-expander-card/chapter/style/styling-examples

Adjusts the arrow position to the left when using a title card without an overlay. It targets the `.title-card-header` class specifically.

```yaml
type: custom:expander-card
title-card:
  type: entity
  entity: sensor.weather
style: | 
  .title-card-header {
    flex-direction: row-reverse !important;
    padding: 0.8em 0 !important;
  }
cards:
  - type: entity
    entity: sensor.humidity

```

--------------------------------

### Change Hover/Press Ripple Color for No Title Card

Source: https://melled.github.io/lovelace-expander-card/chapter/style/hover

Use this CSS to change the hover and press ripple color for a card without a title. Apply this to the `.header` class.

```css
style: |
  .header {
    --ha-ripple-color: red;
  }

```
Tokens:
Raw