---

name: ha-custom-cards description: "Configure HACS custom cards for beautiful Home Assistant dashboards including ApexCharts, modern-circular-gauge, bubble-card, mini-graph-card, and mushroom. Use when creating visually rich dashboards with graphs, gauges, separators, or time-series visualizations. Covers card configurations, color schemes, layouts, and HACS installation."

Home Assistant Custom Cards

Configure HACS (Home Assistant Community Store) custom cards for enhanced dashboard visualizations.

Installed Cards

Quick Start

Modern Circular Gauge (VALIDATED)

Copytype: custom:modern-circular-gauge
entity: sensor.temperature
name: Temperature
min: 10
max: 40
needle: true
segments:
  - from: 10
    color: "#3498db"    # Cold - blue
  - from: 18
    color: "#2ecc71"    # Comfortable - green
  - from: 26
    color: "#f1c40f"    # Warm - yellow
  - from: 32
    color: "#e74c3c"    # Hot - red

ApexCharts with Time Axis (VALIDATED)

CRITICAL: The span.end field must be one of: "minute", "hour", "day", "week", "month", "year", "isoWeek"

Copytype: custom:apexcharts-card
header:
  show: true
  title: 24 Hour History
  show_states: true
graph_span: 24h
span:
  end: hour  # REQUIRED: must be minute/hour/day/week/month/year/isoWeek
yaxis:
  - min: 0
    max: 50
    decimals: 1
apex_config:
  chart:
    height: 200
  xaxis:
    type: datetime
    labels:
      datetimeFormatter:
        hour: "HH:mm"
  legend:
    show: true
series:
  - entity: sensor.temperature
    name: Temperature
    color: "#e74c3c"
    stroke_width: 2

Common ApexCharts Errors:

• WRONG: "span": {"end": "now"} → ❌ Causes parsing error
• CORRECT: "span": {"end": "hour"} → ✅ Valid value

Bubble Card Separator

Copytype: custom:bubble-card
card_type: separator
name: Section Name
icon: mdi:thermometer

Mushroom Climate Card (VALIDATED)

Copytype: custom:mushroom-climate-card
entity: climate.ac_unit
name: AC Name
hvac_modes:
  - "off"
  - cool
  - heat
  - auto
show_temperature_control: true
collapsible_controls: true

Common Patterns

Grid Layout with Gauges

Copytype: grid
columns: 3
square: false
cards:
  - type: custom:modern-circular-gauge
    entity: sensor.officeht_temperature
    name: Temperature
    min: 10
    max: 40
    needle: true
    segments:
      - from: 10
        color: "#3498db"
      - from: 18
        color: "#2ecc71"
      - from: 26
        color: "#f1c40f"
      - from: 32
        color: "#e74c3c"
  - type: custom:modern-circular-gauge
    entity: sensor.officeht_humidity
    name: Humidity
    min: 0
    max: 100
    needle: true
    segments:
      - from: 0
        color: "#e74c3c"
      - from: 30
        color: "#f1c40f"
      - from: 40
        color: "#2ecc71"
      - from: 60
        color: "#f1c40f"
      - from: 70
        color: "#e74c3c"

See examples/examples.md for complete environmental dashboard section with separators and graphs.

ApexCharts Advanced Features

Valid Span Configuration (VALIDATED)

CRITICAL: Always use one of these valid values for span.end:

Copyspan:
  end: minute   # Start of current minute
  end: hour     # Start of current hour
  end: day      # Start of current day
  end: week     # Start of current week
  end: month    # Start of current month
  end: year     # Start of current year
  end: isoWeek  # Start of ISO week (Monday)

Never use: "now" or other string values - these cause errors.

Dual Y-Axis

Copytype: custom:apexcharts-card
header:
  show: true
  title: Temperature & Humidity
graph_span: 24h
span:
  end: hour
yaxis:
  - id: temp
    min: 0
    max: 50
    decimals: 1
  - id: humidity
    opposite: true
    min: 0
    max: 100
series:
  - entity: sensor.temperature
    name: Temperature
    yaxis_id: temp
    color: "#e74c3c"
    stroke_width: 2
  - entity: sensor.humidity
    name: Humidity
    yaxis_id: humidity
    color: "#3498db"
    stroke_width: 2

Annotations (Sunrise/Sunset)

WARNING: JavaScript template annotations may cause errors. Use with caution.

Copyapex_config:
  annotations:
    xaxis:
      - x: "${ new Date(states['sun.sun'].attributes.next_rising).getTime() }"
        borderColor: "#FFA500"
        label:
          text: Sunrise
          style:
            background: "#FFA500"

Note: If annotations cause configuration errors, remove them or use static timestamps instead.

See references/reference.md for complete ApexCharts advanced features and time formatting options.

Supporting Files

• examples/examples.md - Comprehensive examples (environmental dashboard section, grid layouts, mushroom cards, ApexCharts patterns)
• references/reference.md - Color schemes, HACS installation (UI and API), troubleshooting, best practices, official documentation

HACS Installation

Via UI

1. Open HACS → Frontend
2. Search for card name
3. Click Download
4. Restart Home Assistant

Via API (Programmatic)

Copyimport json
import websocket

ws_url = "ws://192.168.68.123:8123/api/websocket"
ws = websocket.create_connection(ws_url)

# Auth
ws.recv()
ws.send(json.dumps({
    "type": "auth",
    "access_token": os.environ["HA_LONG_LIVED_TOKEN"]
}))
ws.recv()

# Install card by repository ID
ws.send(json.dumps({
    "id": 1,
    "type": "hacs/repository/download",
    "repository": 151280062,  # mini-graph-card
}))
response = json.loads(ws.recv())
ws.close()

Common Error Patterns

1. ApexCharts span error

Check span.end uses valid value (hour/day/week/month/year)

Copy# WRONG
span:
  end: now  # ❌

# CORRECT
span:
  end: hour  # ✅

2. Entity not found

Verify entity exists in Developer Tools → States

3. Card not loading

Check HACS installation and browser console (F12)

4. JavaScript template error

Remove or simplify template annotations

See references/reference.md for complete troubleshooting guide.

Best Practices

1. Use meaningful colors: Red for warnings/hot, blue for cold/water, green for normal
2. Test incrementally: Add cards one at a time and validate
3. Check browser console: View errors in browser console (F12)
4. Validate entities: Ensure entity IDs exist before using in cards
5. Restart HA after HACS install: Custom cards require restart to activate

Notes

• ApexCharts span.end MUST use valid enum values (minute/hour/day/week/month/year/isoWeek)
• All HACS cards require Home Assistant restart after installation
• Repository IDs: mini-graph-card (151280062), apexcharts-card (331701152), bubble-card (680112919)
• JavaScript template annotations may cause errors - test before deploying
• Use Developer Tools → States to verify entity IDs exist