Français

Custom Gauge Card — Home Assistant card

Animated circular LED gauge for Home Assistant: colored zones, markers, visual alarms, trend and control buttons.

Available on HACSGaugesVersion v2.2★ 29 starsMinimum Home Assistant 2024.1.0

Open in HACS · Code on GitHub

Custom Gauge Card preview

Overview

Custom Gauge Card shows a Home Assistant sensor as a circular gauge made of animated LEDs. The arc, scale ticks, colored zones and markers are fully adjustable, from a full circle to a C-shaped gauge, with a bidirectional mode for negative values.

The card flags out-of-range values with visual alarms triggered by any entity, shows the 24-hour trend, and can control up to four entities (lights, switches, scenes, scripts) from buttons placed under the title.

Features

  • Circular gauge with animated LEDs
  • Smooth and fluid value transitions
  • Dynamic shadow and lighting effects
  • Multi-entity alarms with four visual effects (pulsating shadow, blinking LEDs, blinking value, pulsating card border)
  • Bidirectional display for thermometer-style visualization with negative values
  • Customizable themes (light, dark, custom)
  • Configurable arc span and start angle (arc_sweep, arc_start)
  • SVG scale overlay with major/minor ticks and value labels (scale_ticks)
  • Define colored zones to visualize value ranges
  • Add static markers with labels for specific reference points
  • Dynamic markers that follow entity values in real-time
  • Flexible color and opacity configuration
  • Full support for bidirectional mode
  • Evolution over 24 hours (or any period)
  • Percentage or absolute change with directional arrow

Installation

  1. In Home Assistant, open HACS (“Open in HACS” button above), add the guiohm79/custom-gauge-card repository if asked, then install “Custom Gauge Card” and reload your browser.
  2. Without HACS: download custom-gauge-card.js from the latest GitHub release, copy it to config/www/, then add the resource /local/custom-gauge-card.js (type “JavaScript module”) in Settings → Dashboards → Resources.

Configuration

type: 'custom:custom-gauge-card'
entity: sensor.processor_use
min: 0
max: 100
title: Processor

Options

OptionTypeDefaultDescription
entity (required)stringEntity to display
attributestringAttribute of the entity to display instead of its state (e.g. current_temperature)
namestringName displayed below the gauge
unitstringUnit of measurement
minnumber0Minimum value
maxnumber100Maximum value
decimalsnumber0Number of decimal places
gauge_sizenumber200Gauge size in pixels
center_sizenumber120Center size in pixels
led_sizenumber8LED size in pixels (diameter; for rect, the segment width along the arc)
led_shapestringroundv2.4: round (LEDs) or rect (radial segments, hi-fi VU meter style)
led_lengthnumberled_size × 2v2.4: rect only — radial length of the segments in pixels. Segments grow inward: their outer edge stays where round LEDs sit
led_corner_radiusnumber1v2.4: rect only — corner rounding in pixels
leds_countnumber100Number of LEDs
bidirectionalbooleanfalseEnable bidirectional display (thermometer-style for negative values)
bidirectional_referencenumberautov2.5: Bidirectional only — value the LEDs grow from, in the sensor unit. Default: 0 when it lies between min and max, otherwise the midpoint. Clamped to [min, max]
card_widthstringautoWidth of the card container (e.g. "300px")
card_heightstringautoHeight of the card container (e.g. "350px")
card_paddingstring16pxPadding of the card container
themestringdefaultTheme: default, light, dark, custom
custom_backgroundstringBackground color (custom theme)
custom_gauge_backgroundstringGauge background (custom theme)
custom_center_backgroundstringCenter background (custom theme)
custom_text_colorstringText color (custom theme)
custom_secondary_text_colorstringSecondary text color (custom theme)
title_font_familystringinheritFont family for the title (e.g., "Roboto, Arial, sans-serif")
title_font_sizestring16pxFont size for the title
title_font_weightstringnormalFont weight for the title (e.g., "normal", "bold", "600")
title_font_colorstringCustom color for the title (overrides theme color)
value_font_familystringinheritFont family for the center value (e.g., "Roboto, Arial, sans-serif")
value_font_sizestring32pxFont size for the center value
value_font_weightstring/numberboldFont weight for the center value (e.g., "normal", "bold", 300-900)
value_font_colorstringCustom color for the center value (overrides theme color)
unit_font_sizestring16pxFont size for the unit symbol
unit_font_weightstring/numbernormalFont weight for the unit (e.g., "normal", "bold", 300-900)
unit_font_colorstringCustom color for the unit (overrides theme secondary color)
arc_sweepnumber360Arc span in degrees (30–360). Use values below 360 for a partial gauge (e.g. 270 for a C-shape)
arc_startnumber0Start angle in degrees from the top/12 o'clock position, clockwise
scale_ticksbooleanfalseShow SVG graduation overlay on the gauge
scale_stepsnumber5Number of major tick intervals
scale_labelsbooleantrueShow value labels at each tick
tap_actionobject{action: more-info}Configurable click behavior
smooth_transitionsbooleantrueEnable smooth transitions
animation_durationnumber800Animation duration in ms
enable_shadowbooleanfalseEnable outer shadow
center_shadowbooleanfalseEnable center shadow
center_shadow_blurnumber30Center shadow blur
center_shadow_spreadnumber15Center shadow spread
center_shadow_pulsebooleanfalseDeprecated in v2.2 — see Alarms. Enable pulsation alarm on center shadow
center_shadow_pulse_durationnumber1000Deprecated. Duration of one complete pulsation cycle in ms
center_shadow_pulse_minnumberminDeprecated. Minimum value of alarm zone (uses real sensor values, not percentages)
center_shadow_pulse_maxnumbermaxDeprecated. Maximum value of alarm zone (uses real sensor values, not percentages)
center_shadow_pulse_intensitynumber0.5Deprecated. Minimum intensity during pulsation (0-1)
conditionstringrangeSee the condition table below
min / maxnumbergauge min/maxBounds for range and outside
valuenumber0Threshold for above, below, equal
statestringonCompared string for state and state_not
effectstringshadow_pulseSee the effect table below
colorstringseverity colorAlarm color — ignored by leds_blink
durationnumber1000One full cycle, in ms (minimum 100)
intensitynumber0.5Trough of the cycle, 0 = full flash, 1 = no visible pulse
transparent_card_backgroundbooleanfalseMake the main card background transparent
transparent_gauge_backgroundbooleanfalseMake the gauge circle background transparent
transparent_center_backgroundbooleanfalseMake the center circle background transparent
hide_shadowsbooleanfalseHide all box-shadows
hide_inactive_ledsbooleanfalseHide inactive (gray) LEDs, showing only active LEDs
show_trendbooleanfalseShow the trend indicator (change over trend_hours)
trend_modestringpercentv2.5: percent (relative change) or absolute (change in the sensor unit, e.g. ↑ 0.6 °C). A relative change from 0 always falls back to absolute
trend_positionstringbottom-rightv2.5: bottom-right, bottom-left, top-right, top-left or below-title (in the card flow, between the title and the button bar — never overlaps)
trend_hoursnumber24v2.5: Length of the trend window, in hours
trend_update_intervalnumber300v2.5: How often the start-of-window value is re-read from the history, in seconds (minimum 60). 0 reads it once, like before 2.5. The current value is always the live one
trend_show_periodbooleanfalsev2.5: Show the period (24 h) next to the variation
trend_font_sizestring12pxv2.5: Font size of the indicator
trend_backgroundstringrgba(0,0,0,.6)v2.5: Background of the indicator (any CSS value, e.g. transparent)
trend_up_color / trend_down_color / trend_stable_colorstring#4caf50 / #f44336 / #ffeb3bv2.5: Arrow colors. "Stable" means the change rounds to zero at the displayed precision
button_icon_sizenumber22Default icon size for all buttons (in pixels)
buttons_layoutstringbarbar (under the title) or corners (pre-2.3 placement, honors each button's position)
markerslistList of static markers with value, color, label (uses real sensor values)
dynamic_markerslistList of dynamic markers that follow entity values
zoneslistList of zones with from, to, color, opacity (uses real sensor values)
severitylistUPDATED: List of thresholds with value, color for LEDs (uses real sensor values, not percentages)
severity_modestringv2.4: steps (default) — one flat color per zone; gradient — the whole bar takes one color, blended in RGB between the two thresholds around the current value; gradient_arc — each LED takes the color of its own position, so the lit part shows the full gradient
power_save_modebooleanfalsePause updates when invisible
power_save_thresholdnumber10Visibility threshold (%)
update_intervalnumber1000Update interval in ms
debounce_updatesbooleanfalseLimit update frequency

FAQ

How do I install Custom Gauge Card?

With HACS: add https://github.com/guiohm79/custom-gauge-card as a custom repository (Dashboard / Lovelace category), install the card, then reload your browser. The “Open in HACS” button on this page adds the repository for you. Home Assistant 2024.1 or newer is required.

Do I need to write YAML?

No. The card has a full visual editor with collapsible sections for every setting. YAML is still available to copy a configuration from one dashboard to another.

Can the gauge show negative values?

Yes: with bidirectional: true, the gauge starts from zero and lights up on either side, like a thermometer.

Can a visual alarm be triggered by another entity?

Yes. Alarms accept any entity and four effects: pulsating shadow, blinking LEDs, blinking value or pulsating card border.

More cards