Home Assistant Custom Cards

Works with HACS installation (UI and API), Lovelace YAML dashboards, and custom card configurations.

Home Assistant Custom Cards

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

Installed Cards

When to Use This Skill

Use this skill when you need to:

• Create circular gauge visualizations with color segments for temperature, humidity, or other metrics
• Build advanced time-series graphs with ApexCharts for multi-sensor comparisons
• Add section separators with icons using bubble-card for dashboard organization
• Install HACS custom cards programmatically via WebSocket API
• Troubleshoot ApexCharts span.end errors with validated configurations
• Build modern Mushroom-style entity cards

Do NOT use when:

• Native Home Assistant cards meet your needs (prefer built-in cards for simplicity)
• You haven't verified entity IDs exist before using them in custom cards
• Building dashboards without checking browser console for errors

Quick Start

All configurations in this skill are validated and tested. Critical errors (like ApexCharts span.end) are documented with solutions.

Usage

1. Install via HACS: Use UI (HACS → Frontend → Search) or API (WebSocket hacs/​repository/​download)
2. Choose card type: Gauge (circular), graph (ApexCharts/​mini-graph), separator (bubble-card), entity (mushroom)
3. Apply configuration: Copy validated YAML from examples below
4. Verify: Check browser console (F12) for errors, restart HA if card doesn't load
5. Customize: Adjust colors, min/​max values, time spans based on sensor type

Modern Circular Gauge (VALIDATED)

type: 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"

type: 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

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

Mushroom Climate Card (VALIDATED)

type: 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

type: 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:

span:
  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

type: 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.

apex_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)

import 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)

# 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