The easiest way to install the expander card is through the Home Assistant Community Store (HACS). You can use the direct HACS integration link to add the repository to your sources and open the integration automatically.

Alternatively, you can add the repository manually in HACS by following the HACS custom repositories documentation using the repository URL: https://github.com/Alia5/lovelace-expander-card

To install the card without HACS, follow these two steps:

1. Download the card

Download the lovelace-expander-card.js file and place it in your Home Assistant <config directory>/www/ folder.

2. Link the card to your Lovelace UI

Add the resource to your ui-lovelace.yaml file so Home Assistant knows where to find the JavaScript file.

Note: The /www/ directory in Home Assistant is mapped to the /local/ URL path.

# 1. Download the card
```bash
wget https://github.com/Alia5/lovelace-expander-card/releases/download/latest/lovelace-expander-card.js
mv lovelace-expander-card.js /config/www/

2. Link the card to your lovelace ui

resources:
  - url: /local/lovelace-expander-card.js
    type: js

The expander-card can remember whether it was expanded or collapsed across browser sessions using the expand-id configuration key.

When an expand-id is provided, the card's state (expanded or collapsed) is stored in the browser's localStorage under the key expander-{expand-id}. This allows the user's preferred view to persist when they refresh the page or return to the dashboard.

# Example of persisting state with a unique ID
type: custom:expander-card
expand-id: "living_room_lights"

Instead of a simple text title, you can use the title-card option to render a full Home Assistant card as the header of the expander. This allows for more complex headers (e.g., showing a sensor value or a specific button).

Related options for custom title cards:

• title-card: The configuration object for the card used as the header.
• title-card-button-overlay: If true, the toggle button is positioned as an overlay on the title card.
• title-card-padding: Custom padding for the title card container.
• title-card-button-overlay (via overlay-margin): Controls the margin of the toggle button when in overlay mode.

type: custom:expander-card
title-card:
  type: sensor
  entity: sensor.temperature
title-card-button-overlay: true
  overlay-margin: 1em

The ExpanderConfig interface defines the YAML configuration options available for the Lovelace Expander Card in Home Assistant. Use these keys to control the layout, styling, and behavior of the expander and its children.

type: custom:lovelace-expander-card
title: "My Expander"
gap: "10px"
padding: "10px"
'button-background': "#ff0000"
# Optional settings
expanded: true
'title-card':
  type: markdown
  content: "Custom Title"
cards:
  - type: button
    name: "Child Card"

The lovelace-expander-card package exports the ExpanderCard.svelte component as the default export. This component is used by Home Assistant to render the expander card UI. When installed, the card registers itself on the window.customCards array, allowing Home Assistant to identify the card type and metadata.

import ExpanderCard from './ExpanderCard.svelte';

The following configuration keys are available for the lovelace-expander-card:

# Layout and Spacing
gap: string             # Spacing between elements
padding: string         # Padding for the card
'child-padding'?: string # Padding for child cards
'title-card-padding'?: string
'overlay-margin'?: string

# Content and Structure
title: string            # The main title text
cards?: { type: string }[] # List of child card configurations
'title-card'?: LovelaceCardConfig # A custom card to use as the title

# Behavior and State
expanded?: boolean        # Initial expanded state
'expand-id'?: string     # ID for expansion control
clear?: boolean          # Clear state
'clear-children'?: boolean # Clear children state

# Styling
'button-background': string # Background color for the expander button
'title-card-button-overlay'?: false