Ha Custom Cards

Home Assistant Custom Cards

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

Installed Cards

Quick Start

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