-
Notifications
You must be signed in to change notification settings - Fork 3
Visual Editor
Navigate: Configuration overview · General Settings · Entity Settings · Option Index
The card ships with a full visual editor — no YAML required. Every option in this documentation is reachable from the Lovelace UI. Changes apply immediately without a page reload.
The General Settings panel is divided into six tabs to reduce clutter:
| Tab | Contents |
|---|---|
| Chart | Chart mode, graph data (hours to show, points/hour, group by, update interval, visible window, scroll mode) and the visual options (grid, animate, stacked, sparkline, auto scale + custom scale rules, compact legend, auto hide, export button…) |
| Card | Header (title, size, alignment, color), icon (MDI or image, position, size), card styling (height, background, border, radius, padding, background image + blur) and localization (card language, time zone) |
| Overlay | On-card overlays: interval picker, attribute list, tooltip / zoom / scroll sync, energy date sync, battery icon, tooltip settings and annotations |
| X Axis | Labels (date format, font size, opacity, X axis interval), visibility and grid style |
| Y Axis | Labels (custom axis text, ticks, decimals, font), visibility (Y and Y2, logarithmic), grid style and bounds (min range, lower/upper bounds) |
| Calendar | Date navigation (the built-in date picker: modes, position, sync group, presets) and the time window (graph start, show full period) |
Tabs that don't apply to the current chart mode are hidden entirely (see Dynamic Editor Behavior), and settings that depend on a toggle are automatically dimmed while the parent is off — for example, Sync Group is disabled when Tooltip Sync is off.
Each entity panel has six tabs in a 3×2 grid:
| Tab | Contents |
|---|---|
| General | Enabled toggle, entity picker, statistic ID, custom name, custom unit, tooltip name and tap action |
| Basic | Data settings: Y axis, aggregation (plus Damp midnight reset artifacts / Ignore transient zeros), attribute, decimals, points/hour, number format — and the Legend block: Show in Legend with Min / Avg / Max / Last / Sum / Live |
| Graph | Graph type (line / step / bar / candlestick), extrema, average line, moving averages, range band, period comparison, break on gaps, line / fill / data points, Y axis range |
| State Row | State visibility and layout, primary state, trend icon, timestamp and name/state positioning |
| Colors | Base colors (line/fill, point, icon, state), rise/fall colors and color thresholds with transition mode |
| Advanced | Advanced calculations (time offset, value transform, value factor, cost view, forecast horizon), state map and attribute data source |
Entity options also adapt dynamically based on Chart Mode — see Dynamic Editor Behavior.
Entities can be reordered by dragging the grip handle (⠿) on the left side of each entity row. The order determines drawing order on the graph and row order in the state display.
Every configuration field has an info tooltip (ⓘ) with a detailed explanation. Hover or tap the icon next to any label to learn what the option does, see practical examples, and understand how it interacts with other settings.
The visual editor adapts in real time based on the current configuration. Options that don't apply to the current chart mode are hidden — down to the individual toggle, not just whole tabs. A heading disappears once every field under it is hidden, and a tab disappears once all of its headings are; a single surviving field keeps its tab. If the tab you are on disappears after a chart-mode change, the editor moves you to another tab that is still available.
Hiding never changes your configuration (v3.32). Anything you set in YAML for a hidden option is kept and reappears as soon as you switch back to a chart mode that uses it.
The rule for hiding is deliberately conservative: an option is hidden only where it provably has no effect. Anything that reaches the shared data pipeline, the legend, the state row or the tooltip counts as in use and stays visible everywhere — which is why break_on_null, points_per_hour, invert and the colour thresholds show in every mode even though they are not all "drawing" options.
Changing the Chart Mode dropdown instantly reconfigures the entire editor. The card-level settings are organized into six tabs (Chart, Card, Overlay, X Axis, Y Axis, Calendar) — irrelevant tabs disappear entirely based on the chart mode.
| When Chart Mode is… | Visible tabs | What's hidden inside |
|---|---|---|
| Timeline | All six tabs | Nothing — full editor |
| Scatter | Chart, Card, Overlay, X Axis, Y Axis, Calendar | Stacked / Sparkline / Animate / Auto Scale (+ Custom Scale Rules) / Visible Window + Scroll Mode / Extended Window hidden in Chart. In X Axis the label options stay (X Label Size / Opacity / Color) — what goes is X Ticks, Date Label Color, X Axis Interval, Bar Spacing and the whole Grid block; in Y Axis the bounds, the Y2-Axis and Y Ticks toggles, Round Ticks, the grid block, Y Axis Format (number format) and Logarithmic go — the label, tick-count, decimals and tick-format options stay. |
| Pie / Ranking / Polar Area / Radial Bar / Radar | Chart, Card, Overlay, Calendar | X Axis and Y Axis tabs gone. Chart keeps only the mode-relevant blocks (Pie block for pie, Ranking's Min Value, …). Overlay keeps the interval picker, attribute list, points/hour picker, group-by picker, tooltip and battery blocks. |
| Gauge / Box Plot / Waterfall / Histogram | Chart, Card, Overlay, Calendar | X Axis and Y Axis tabs gone — these modes read no axis settings at all. Gauge adds its own block in Chart; Histogram its Bins; Waterfall its Total. |
| Heatmap / Calendar | All six tabs | The Y Axis tab keeps only the label and format options — bounds, ticks, grid, number format and Logarithmic go. |
| State Timeline | Chart, Card, Overlay, X Axis, Calendar | Y Axis tab gone (no Y values). The X Axis tab shows label options only — size, opacity, color, and date color. |
| Sparkline mode | Chart, Card | Everything else gone — sparkline is chrome-free. Inside Card, only Card Styling and Localization remain. |
Each entity's expanded settings are organized into six tabs in a 3×2 grid: General, Graph, Basic, State Row, Colors, Advanced. Switching the chart mode reshapes the visible options.
Below is the complete list of entity options that are mode-restricted. Anything not in this table is visible in every chart mode — including Aggregate Function, Attribute, Points/Hour, Decimals, Number Format, Break on Gaps, Y Axis (Primary/Secondary), Invert, Value Factor, Value Transform, Fixed Value, State Map, Offset, Forecast Horizon, Colour Thresholds, the rest of the State Row block and the whole Legend block.
| Option | Tab | Visible in… |
|---|---|---|
| Graph Type, Line Width, Show Line, Line Style, Bezier (Smooth), Data Points, Point Size, Show Extrema (+ min/max, timestamp, colour, font size, background), Range Band, Show Average, Moving Averages, Data Labels, Z-Index, Rise/Fall Colors, Period Comparison | Graph / Colors | Timeline |
| Stack Group | Graph | Timeline, and only while the card's Stacked toggle is on |
| Show Fill | Colors | Timeline, Radar |
| Point Color | Colors | Timeline, Scatter, Radar |
| Gradient | Colors | Timeline, Ranking, Radar, Gauge |
| Y Axis Range (Lower / Upper Bound) | Graph | Timeline, Scatter, Radial Bar, Radar, Heatmap, Calendar, Gauge |
| Tooltip Name | General | Timeline, Pie, Ranking, Radial Bar, Polar Area, Radar, Gauge |
| Needle Color | Colors | Gauge |
| Trend Icon (+ period, size, up/down/stable colours) | State Row | All modes except State Timeline |
Three corrections landed here in 3.32. Invert (Mirror) was documented as Timeline-only; it has always worked in every mode and is now shown in every mode. Colour Thresholds used to be hidden in Pie, Box Plot, Waterfall, Histogram and State Timeline even though they colour the legend, the state row and the tooltip there — they are now shown everywhere. Y Axis (Primary/Secondary) also stays visible everywhere: besides choosing an axis it selects which of
y_axis_format/y2_axis_formatformats that entity's numbers, and that applies in every chart mode.
When sparkline is enabled (Timeline mode only):
- Card tab: Header and Icon sections disappear; Card Styling and Localization remain
- Overlay tab: Hidden entirely — overlays don't render in sparkline mode
- X Axis / Y Axis / Calendar tabs: Hidden entirely
- The card renders with zero chrome — no toolbar, axes, grid, or legend
Within each entity, toggle states cascade downward — disabling a parent hides or disables all its children:
| When this is… | These become hidden / disabled |
|---|---|
show_graph: off |
The Graph block is marked locked (dashed border, 65% opacity) and its contents — Stack Group, Show Average, Break on Gaps, Data Labels — are dimmed and disabled. Graph Type, Z-Index, Extrema, Line, Range Band, Data Points and Fill are separate blocks with their own master switches and are not affected |
show_line: off |
Line Width, Bezier, Line Style — disabled |
show_fill: off |
Gradient — disabled |
show_state: off |
Show Last, Adaptive Color, Icon, Align, all Size fields — disabled |
show_state: gauge |
Nothing is disabled — the State Row control is a plain On/Off dropdown and the editor treats every value other than false as On |
show_trend_icon: off |
Trend Period, Trend Icon Size — disabled |
The "Add Entity" button automatically hides when the chart mode's limit is reached:
| Chart Mode | Max Entities | Notes |
|---|---|---|
| Timeline | Unlimited | Mix line, step, bar freely |
| Scatter | 2 | Entities labeled X and Y in the editor |
| Pie / Ranking | Unlimited | Each entity = one slice / bar |
| Radial Bar | Unlimited | Each entity = one concentric ring |
| Polar Area | Unlimited | Each entity = one equal-angle slice |
| Radar | 3+ minimum | Each entity = one spoke of the polygon |
| Heatmap / Calendar | 1 | Only the first entity is used |
Some options depend on or conflict with each other:
| If you set… | Then… |
|---|---|
value_transform set |
Runs after value_factor. Available variables: x, first, last, min, max, avg, index. State row shows the transformed value |
offset set (per entity) |
Data is fetched from a shifted time window but displayed aligned with the current window. Same entity with different offsets = period comparison at full graph quality |
stacked: true |
Only affects entities with the same y_axis and graph_type
|
auto_scale_points: true |
Only scales entities that inherit the card-level points_per_hour — entity-level overrides are not affected |
auto_scale_rules set |
Only consulted when auto_scale_points: true. The smallest matching up_to_hours threshold wins; periods beyond every threshold use the built-in auto-scale table |
color_thresholds enabled |
Cannot combine with rise_fall_colors on the same entity |
show_state: gauge |
Uses entity lower_bound / upper_bound as gauge min/max; falls back to stats if not set |
chart_mode: heatmap + color_thresholds
|
Heatmap cells use threshold colors instead of single-color opacity gradient |
sparkline: true |
Only works in Timeline mode; ignored in other chart modes |
max_visible_interval set |
Enables scroll; scroll_mode controls whether scrollbar is visible or mouse-wheel only |
show_y_axis: false |
Hides primary (left) axis labels; secondary axis is not affected |
show_y2_axis: false |
Hides secondary (right) axis labels; primary axis is not affected. Right padding shrinks. |
show_legend: true |
Compact Legend appears below graph. Combine with show_state: false on entities for maximum graph space |
legend_stats |
Only takes effect when entity show_in_legend is true. Any combination of min, avg, max, last, sum, live
|
align_state: bottom-* |
State row renders below the graph instead of above. Can be mixed — some entities top, some bottom |
show_range_band: true |
Only visible in Timeline mode with line/step entities. Band is drawn behind the normal line and fill. Tooltip adds a min → max row |
chart_mode: radialbar |
Uses lower_bound / upper_bound per entity to define the 0–100% ring fill. Falls back to stats min/max if not set |
chart_mode: radar |
Requires at least 3 entities. Uses lower_bound / upper_bound per entity for normalization |
energy_date_sync: true |
Card time range follows the Energy dashboard date picker. When viewing today, X axis ends at the current time and live updates continue. When viewing a past date, live updates are paused. Overrides hours_to_show while active |
statistic_id set (with empty entity) |
Data is fetched from the statistics database only — no History API call. State row shows last statistics value. WebSocket live updates are skipped for this entity |
color: "{{ ... }}" |
Template is evaluated by Home Assistant itself and the card updates instantly whenever the result changes — no polling. Editor color picker dims automatically. Falls back to the raw template string if resolution fails |
graph_start: tomorrow |
Window is tomorrow 00:00 → end of day. show_full_period is not required. History fetch is skipped (no past data in tomorrow's range). Ideal with data_attribute for forecast/spot price data |
y_grid_style / x_grid_style
|
Only effective when show_grid: true. Applies inline SVG styles that override the default CSS class |
decimals on pie/radial entity |
Controls both value precision and percentage precision in slice labels, tooltips, and center totals |
compare set (per entity) |
A faded, dashed ghost of the previous period is drawn under the main series and follows the exact same aggregation pipeline — a list of comparisons draws one ghost per entry, each reaching further back via periods_back. Legend / state-row clicks toggle main + ghosts together. Ignored for candlestick, fixed_value, and data_attribute entities and in sparkline mode |
show_legend: "{{ ... }}" (or any templatable toggle) |
Template is resolved server-side like color templates and updates live; the default applies until the first result arrives. The editor locks the checkbox — dimmed, with a {…} badge and a tooltip showing the template — and never overwrites it |
aggregate_func: max (per entity) |
A Damp midnight reset artifacts checkbox appears under the Aggregation dropdown in the editor — the UI switch for damp_reset_boundary, shown only while the aggregate is max
|
aggregate_func: change (per entity) |
An Ignore transient zeros checkbox appears under the Aggregation dropdown — the UI switch for change_ignore_zero, shown only while the aggregate is change
|