Agent skill

ha-custom-cards

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.

View SKILL.md on GitHub Repository
Stars 163
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/other/ha-custom-cards-dawiddutoit-custom-claude

SKILL.md

Home Assistant Custom Cards

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

Installed Cards

Card Purpose Repository ID
mini-graph-card Compact sparkline graphs 151280062
bubble-card Section separators with icons 680112919
modern-circular-gauge Beautiful circular gauges 871730343
lovelace-mushroom Modern entity cards 444350375
apexcharts-card Advanced graphs with time axis 331701152

Quick Start

Modern Circular Gauge (VALIDATED)

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

yaml
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

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

Mushroom Climate Card (VALIDATED)

yaml
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

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

yaml
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

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

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

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

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

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

majiayu000/claude-skill-registry

agent-ops-spec

Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-state

Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-spec

Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-testing

Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-testing

Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-state

Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.

163 31
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results