Entity Settings
Navigate: Configuration overview · General Settings · Visual Editor · Option Index
Per-entity options, organized to match the six tabs in each entity editor.
Entity identity, statistic source, display name, custom unit, tap behavior, and availability.
Since v3.32 the editor only shows options the selected chart mode can actually use. Gating happens per field: a section heading disappears once everything under it is hidden, a tab once all its headings are, and you are moved to the first surviving tab. Nothing is deleted — a hidden option keeps its YAML value and reappears when you switch modes back.
| Option | Type | Default | Description |
|---|---|---|---|
entity
|
string | required | HA entity ID. Can be left empty when using statistic_id. |
statistic_id
|
string | null |
For imported/external statistics that have no regular entity (e.g. gazpar:gazpar_consumption). These exist only in the statistics database. Leave empty for normal entities. See External Statistics. |
name
|
string | null |
Custom display name for the state row. Leave empty to show the entity's friendly_name (the default). To hide the name instead, use hide_name. Supports HA-style templates: {{ states('sensor.x') }}, {{ state_attr('sensor.x', 'attr') }} with Jinja2 filters like capitalize, upper, replace(). See Template Names. |
tooltip_name
|
string | null |
Override the name shown in the hover tooltip independently from name. Useful when you want a long, descriptive label in the state row but a short label — or no label at all — in the tooltip. Set to an empty string (tooltip_name: "") to hide the name in the tooltip while keeping the swatch and value visible. When unset, the tooltip falls back to name → friendly_name → entity id. |
unit
|
string | null |
Custom unit label (e.g. kWh, °C, %). Overrides the auto-detected unit_of_measurement. Useful for attributes, unitless sensors, or when you want a different label. Appears in state row, tooltip, chart center, and axis labels. |
tap_action
|
object | null |
Action on tapping the state row. See Tap Actions. When left unset (or set to none), tapping the state row instead toggles that entity's visibility on the graph — same as clicking its legend item. Hidden entities dim visually so you can tell what's off at a glance. |
enabled
|
boolean | true |
Set false to make the card behave as if this entity was never configured: nothing is fetched or drawn, comparison ghosts are not created, and no card-wide logic (auto-scale guards, Y-bounds, palette colors) considers it. Its entity id is not even validated — a template placeholder is fine. Built for shared card templates (e.g. Streamline) where some instances lack a sensor: pass a per-instance variable instead of maintaining a separate card. Plain boolean by design (not Jinja-templatable — it affects data fetching); static template engines substitute it before the card sees it. The editor shows disabled rows dimmed with an Enabled toggle. (v3.30)
|
Graph type, lines and fills, points, extrema, averages, range bands, labels, layering, and entity bounds.
| Option | Type | Default | Description |
|---|---|---|---|
compare
|
string/number/object/list | null |
Overlay a faded, dashed ghost series of the same entity from a previous period underneath the main line. Short forms: previous_period, yesterday, last_week, last_month, last_year, a number of hours, or true (= previous_period). Also accepts an object for full styling control (period, color, opacity, line style/width, fill, points, legend, tooltip delta) — or a list of comparison objects, one ghost per entry, each reaching further back via periods_back (1 = previous period, 2 = two periods ago). Timeline charts only — ignored for candlestick, fixed_value, and data_attribute entities and in sparkline mode. See Period Comparison. |
graph_type
|
string | "line" |
line / step / bar / candlestick. Only available in Timeline mode — other chart modes ignore this. See Candlestick (OHLC). |
show_graph
|
boolean | true |
Show this entity on the graph |
auto_hide
|
boolean | false |
Start this single entity hidden — the series is invisible until you reveal it from the legend (the reveal sticks for the session). Per-entity alternative to the card-wide auto_hide_entities. When auto_hide_entities is set, it takes precedence over per-entity values. Editor: Graph tab → Hide on Load. |
show_line
|
boolean | true |
Show the line edge. Timeline mode only. |
show_range_band
|
boolean | false |
Draw a min/max shaded band behind the line showing the value range within each aggregation bucket. The line shows the average while the band shows how much the value fluctuated. See Range Band. Timeline mode only. |
show_points
|
boolean | false |
Show a dot at each data point. Timeline mode only. |
point_size
|
number | auto | Radius of the data point dots in pixels (0.5–20). Leave unset for automatic sizing based on line_width. Also sets the dot size in scatter and radar modes (via YAML; in scatter, set it on the first entity — the one that styles the dots). In the editor the field appears under the Data Points toggle when it is enabled. (v3.29)
|
smooth
|
boolean | true |
Bezier curve smoothing. Timeline mode only. |
line_width
|
number | 2.5 |
Line thickness in pixels. Timeline mode only. |
line_style
|
string | solid |
Line type: solid, dashed, dotted. |
z_index
|
number | 0 |
Draw order / layering. Higher = drawn in front (on top of lower-numbered entities); lower or negative = behind. Default 0 keeps configuration order. Independent of the legend / state-row order, so you can bring a curve to the front or send it behind another without reordering your entities. Timeline mode. |
show_extrema
|
string | "click" |
Min/Max labels: never / click / always. Timeline mode only. |
show_extrema_min
|
boolean | true |
Show the Min value label. Disable to show only the Max — useful for sensors where the minimum is always zero (solar power, rain, etc.). Timeline mode only. |
show_extrema_max
|
boolean | true |
Show the Max value label. Timeline mode only. |
show_data_labels
|
boolean | false |
Print the numeric value of every visible data point right above its bar / line / point — ApexCharts-style. Uses the entity's decimals and number_format settings. Text renders in the entity color with a card-background halo so it stays readable over busy charts. For bars, font size adapts to bar width and labels shrink down to a minimum of 7 px before being skipped. Best paired with reasonable point counts; dense charts produce overlapping labels. Timeline mode only. |
data_labels_font_size
|
number | null |
Override the auto-picked font size for data labels in pixels. Leave empty to inherit the default (10 px for lines, dynamic per-bar for bars). Has no effect when show_data_labels: false. Timeline mode only. |
extrema_show_timestamp
|
boolean | true |
Show the time the extreme value was recorded below each label. Disable for compact display showing only the value. Timeline mode only. |
extrema_color
|
string | null |
Custom font color for extrema labels. Accepts any CSS color or variable. Leave empty for theme default. Timeline mode only. |
extrema_font_size
|
number | 13 |
Font size of the extrema value in pixels. Timestamp text scales proportionally. Timeline mode only. |
extrema_bg_color
|
string | null |
Background color of the extrema label box. Combined with extrema_bg_opacity. Leave empty for theme default. Timeline mode only. |
extrema_bg_opacity
|
number | 1 |
Opacity of the extrema label background (0 = transparent, 1 = solid). Set to 0 for floating text without a visible box. Timeline mode only. |
show_average
|
boolean | false |
Draw a dashed horizontal line at the mean value. Timeline mode only. |
moving_averages
|
list | null |
One or more simple moving-average (SMA) lines drawn over this entity. Each item takes period (length in buckets, required), color, and an optional width. The bucket size comes from points_per_hour / group_by, so a period of 26 means "average of the last 26 buckets". The card extends the history look-back beyond the visible window automatically, so a long period draws fully even when hours_to_show is short. Averages the close for candlesticks, otherwise the bucket value. Plotted on the entity's own Y axis. Set show_label: true on an item to print a small MA7/MA26 label at the end of its line. Timeline mode only. See Moving Averages. |
break_on_null
|
boolean | false |
Break the line at long sensor outages instead of carrying the last known value across the gap. When false (default), the previous known value is carried forward indefinitely — the line stays continuous even during long unavailable / unknown periods. When true, short blips stay connected but outages longer than a threshold (default min(3 × bucket, 30 minutes)) appear as visible breaks in the line. Applies in every chart mode — it changes the bucketed values themselves, not just the drawn line. Does not affect value_transform scripts that return null (those already drop their buckets before this logic runs). See Break on Gaps. |
carry_forward_ms
|
number | null |
Advanced override for the carry-forward threshold in milliseconds. Takes effect regardless of break_on_null. Use this when you want a specific time window instead of the default auto threshold. Applies in every chart mode. |
lower_bound
|
string/number | null |
Y axis minimum / gauge minimum. See Bounds. |
upper_bound
|
string/number | null |
Y axis maximum / gauge maximum. See Bounds. |
stack_group
|
string | null |
Named group for stacked bars/lines. Entities with the same group name stack on top of each other; different groups sit side by side. Leave empty to stack all entities together (default). Requires stacked: true. See Stacked Groups. |
Axis assignment, aggregation, attributes, precision, sampling density, number formatting, and the legend statistics block.
| Option | Type | Default | Description |
|---|---|---|---|
y_axis
|
string | "primary" |
primary (left), secondary (right), or independent (hidden, own scale). Independent entities are scaled to their own min/max — ideal for overlaying sensors with different units for trend comparison. y_axis also selects which axis format the entity's numbers use: secondary formats through y2_axis_format, primary and independent through y_axis_format — and that applies in every chart mode, plus the state row, legend and tooltips, not just Timeline. That is why the field stays visible in the editor in all chart modes. See Independent Y-Axis. |
aggregate_func
|
string | "avg" |
Aggregation: avg / min / max / last / first / median / sum / change / delta / diff. The change option uses HA's native statistics change field — ideal for energy, gas, and water meters with group_by: date/week/month. |
damp_reset_boundary
|
boolean | true |
Expert. The card automatically repairs the midnight carry-over artifact that daily-reset counters (e.g. *_today energy sensors) show when displayed with aggregate_func: max + group_by: date — without it, the first bucket of each day would inherit the previous day's peak. Set to false to disable the heuristic if it damps legitimate peaks near midnight. |
change_ignore_zero
|
boolean | false |
(new in v3.28) For aggregate_func: change on counters whose integration reports a literal 0 while the device is off or restarting and then jumps back to the previous total (instead of going unavailable). Each such dip is normally counted as a meter reset, so the restored value is re-counted as new consumption — inflating daily/monthly totals massively. Enable to skip zero readings entirely; with long-term statistics the change is recomputed from the state column, bypassing the polluted sums. Counters that genuinely reset to zero and keep counting from there still work. Also available as an Ignore transient zeros toggle under the Aggregation dropdown. |
decimals
|
number | 1 |
Decimal places shown in state row and labels |
attribute
|
string | null |
Read an attribute instead of state. Supports dot notation: forecast.0.temperature. In state_timeline mode, pair with state_map to plot the attribute's history (#219). |
points_per_hour
|
number | null |
Per-entity override. Inherits card-level setting if empty. The editor offers the same divisor-of-60 presets as the card-level setting; YAML accepts any integer. |
number_format
|
string | "system" |
Controls how numbers are displayed in the state row and tooltip. system follows HA's locale; comma forces European style (1.234,56); dot forces English style (1,234.56). Useful when mixing sensors from different regional sources. |
show_in_legend
|
boolean | false |
Show a statistics row below the graph for this entity. Which stats are shown is controlled by legend_stats. Editor: Basic tab → Legend. |
legend_stats
|
list/string | ["min","avg","max"] |
Which statistics to display in the legend row. Any combination of min, avg, max, last, sum, live (v3.32). Also accepts a comma- or space-separated string (legend_stats: avg, live). Requires show_in_legend: true. Unlike the others — which all describe the displayed window — live is the entity's state right now, whatever period the chart shows, and it refreshes the moment the entity changes instead of waiting for the next data refresh. It goes through the same pipeline as the state row (attribute, state_map labels, invert / value_factor / value_transform, and the combined ref_entity value), but ignores primary_state_as; for series with no live state (ref_entity, a non-zero offset, long-term statistics) it falls back to the last value in the fetched window. |
Current-value presentation, icon, adaptive coloring, trend indicators, statistics, alignment, and text sizing.
| Option | Type | Default | Description |
|---|---|---|---|
hide_name
|
boolean | false |
Hide this entity's name in the state row (the live value row above the graph), leaving just the value. Only affects the state row — the compact legend and tooltip still show the name. Separately, the legacy name: "" (empty custom name) still hides the name everywhere (state row, legend, and tooltip) and is left untouched. Editor: State Row tab → Hide Name. |
show_state
|
string/boolean | true |
State row display: true (text), false (hidden), "gauge" (half-circle arc). See Gauge Display. |
show_color_dot
|
boolean | true |
Show the colored marker next to this entity in the state row, compact legend, detail legend, timeline tooltip and all chart-mode tooltips. Set to false to hide the marker while keeping the surrounding text in place (text does not shift). Useful when you only have one entity and don't need a color marker, or when color_thresholds causes the static dot color to no longer match the dynamically-colored line / bar / value. |
state_adaptive_color
|
boolean | false |
Automatically tint the state value, icon, and the colored dot with the entity's line color. When color_thresholds are defined, all three follow the threshold-resolved color as the value crosses each band — they stay in sync. For a state_map entity the tint follows the current state's mapped colour (e.g. on → orange, off → blue) rather than the single line colour, falling back to the entity colour when that state has no colour. Quick alternative to setting state_color and icon_color manually. Editor: State Row tab → Adaptive Color. |
show_state_last
|
boolean | false |
Legacy — equivalent to primary_state_as: last. Still honored for backward compatibility. |
primary_state_as
|
string | null |
What appears as the big primary value in the state row. null (default) = live HA state. last = last aggregated graph point. sum / avg / min / max / first = the chosen aggregate over the visible window, shown as a clean number with no "SUM"/"AVG" label prefix. All options work in every chart mode, but last / first are only meaningful for time-based modes (Timeline, Scatter, State Timeline): in Pie, Ranking, Radial Bar, Polar Area, Radar, Heatmap and Calendar they still report the raw series endpoints rather than any visible slice or cell — the editor shows a warning there and suggests sum / avg / min / max instead. Useful for header-only entities (show_graph: false) that just display a computed number. |
show_timestamp
|
boolean | false |
When primary_state_as is min, max, first, or last, also show the time the value was recorded as a subdued suffix next to the main number. Useful for record-tracking cards (coldest day, peak solar, strongest wind, etc.). Format follows the card's datetime_format (or HA locale when set to system). Has no effect for sum / avg (no single timestamp applies). |
show_range_values
|
boolean | false |
Show the visible window's min and max as a subdued (min → max) suffix next to the primary value. Best paired with show_graph: false + primary_state_as: min/max for compact "records" cards (coldest day, peak solar, etc.) where the range otherwise lives only in a tooltip the user can't reach. Available for any aggregate (Last, First, Min, Max, Sum, Avg). When show_range_band: true is enabled on the entity, it uses the more accurate per-bucket band data; otherwise it falls back to the aggregate min/max over the visible window. Has no effect for live State (primary_state_as: null). |
name_position
|
string | null |
Controls how the entity name and primary value are arranged in the state row. null (default) = name to the left of the value (inline). below = value shown larger with the name centered underneath (ApexCharts-style, great for header-only entities and mobile layouts). |
show_second_state_as
|
string | null |
Show a secondary stat value next to the primary state. Options: min, max, avg, sum, first, last. Displays with the same styling as the primary value, with a small label prefix. |
show_trend_icon
|
boolean | true |
Show a ▲ / ▼ / ━ trend direction icon next to the state value. The icon indicates direction only — it is not affected by color_thresholds or rise_fall_colors, but each direction has its own colour option: trend_up_color, trend_down_color, trend_stable_color. The trend icon is never drawn in state_timeline mode. |
trend_period_hours
|
number | 1 |
Time window (in hours) for trend direction calculation. Set 0 for full range. |
align_state
|
string | "left" |
State row position and alignment. Top variants: left / center / right (above the graph). Bottom variants: bottom-left / bottom-center / bottom-right (below the graph). |
icon
|
string | null |
MDI icon in the state row, e.g. mdi:thermometer
|
icon_size
|
string | null |
State row icon size, e.g. 18px
|
name_size
|
string | null |
State row name font size, e.g. 14px
|
state_size
|
string | null |
State row value font size, e.g. 13px
|
trend_icon_size
|
string | null |
Trend icon font size, e.g. 12px
|
trend_up_color
|
string | null |
Colour of the ▲ (rising) trend icon. Leave empty to follow the theme success colour. Editor: State Row tab → Trend Icon → Up Color. Hidden in state_timeline mode. |
trend_down_color
|
string | null |
Colour of the ▼ (falling) trend icon. Leave empty to follow the theme error colour. Editor: Trend Icon → Down Color. Hidden in state_timeline mode. |
trend_stable_color
|
string | null |
Colour of the ━ (stable) trend icon. Leave empty to follow the theme secondary text colour. Editor: Trend Icon → Stable Color. Hidden in state_timeline mode. |
Series, points, state, icon, fill and gradients, directional colors, thresholds, and gauge needle styling.
| Option | Type | Default | Description |
|---|---|---|---|
show_fill
|
boolean | true |
Show the fill area below the line. Timeline mode only. Fill and Gradient are one section together in the editor's Colors tab. |
gradient
|
boolean | true |
Fade the fill from the entity color to transparent. Only applies when show_fill is true. Timeline mode only. |
color
|
string | "#ff4757" |
Line and fill color. Use threshold to drive from color thresholds. Accepts {{ }} Jinja2 templates for dynamic server-side color resolution (e.g. {{ state_attr('sensor.entity_colors','entities')['Temperature'] }}). See Color Templates. |
point_colors
|
string | null |
Color of data point dots. Use threshold for per-point threshold color. Accepts {{ }} templates. |
icon_color
|
string | null |
State row icon color. Use threshold for dynamic color. Accepts {{ }} templates. |
state_color
|
string | null |
State row value text color. Use threshold for dynamic color. Accepts {{ }} templates. |
rise_fall_colors
|
object | null |
Color by rise/fall direction. See Rise/Fall Colors. |
color_thresholds
|
object | null |
Color by value. See Color Thresholds. |
needle_color
|
string | null |
Gauge mode — color of the needle. Use threshold to color it from color_thresholds at the current value, or any CSS color / {{ }} template. Leave empty to follow the value color (threshold-resolved, or the entity color). |
Transforms, comparisons, cost and reference calculations, external data, offsets, state mapping, and compatibility controls.
| Option | Type | Default | Description |
|---|---|---|---|
price_entity
|
string | null |
Multiply every value of this series by the state of another entity over time — the cost view. The price is read as a step function from the price entity's own history (long-term statistics with hourly mean on long windows), and the multiplication happens per consumption slice before bucketing, so each bucket is an exact Σ(valueᵢ × priceᵢ). Intended for aggregate_func: change on energy counters — set unit to the currency. State changes of the price entity auto-refresh the card. Not applied to fixed_value / data_attribute entities. See Cost View. |
price_attribute
|
string | null |
Read the price from an attribute of price_entity instead of its state. Supports dot notation for nested paths (e.g. raw_today.0.value). Only used when price_entity is set. |
ref_entity
|
string | null |
Two-entity math. Combine this entity with a second one over time — the classic case being indoor − outdoor without a template sensor. The reference is read as a step function from its own history, so every sample of this entity is combined with the reference value valid at that moment. A gap in the reference produces a gap here rather than an invented value. With no explicit name, the series is automatically labelled with the combined name — Indoor - Outdoor (the reversed operators swap the sides, so reverse_subtract reads Outdoor - Indoor). When include_attribute_name / use_only_attribute_name is on, both sides are qualified with their own attribute — Current temperature - Target temperature — using ref_attribute for the reference side, rather than one attribute minus a bare entity name (v3.32). fixed_value / data_attribute rows never get a combined name. See Two-Entity Math. (v3.31)
|
ref_op
|
string | "subtract" |
How to combine with ref_entity: subtract (A−B), add, multiply, divide (A÷B), plus reverse_subtract (B−A) and reverse_divide (B÷A). The reversed forms exist because swapping the two entities is not equivalent — the main entity drives the timeline, unit, aggregation and data source, while the reference is only sampled. subtract/add/reverse_subtract combine levels and are refused when aggregate_func is change, diff, sum or delta (those are already per-bucket deltas) — the series renders empty with a console warning. multiply/divide are allowed with any aggregation. An unrecognised value falls back to subtract. (v3.31)
|
ref_attribute
|
string | null |
Read the reference from an attribute of ref_entity instead of its state (dot notation), e.g. temperature on a weather. entity. (v3.31)
|
value_factor
|
number | 0 |
Multiplies value by 10^N. -3 = ÷1000, 2 = ×100 |
value_transform
|
string | null |
JavaScript expression to transform each data value. Available variables: x (current value), first, last, min, max, avg (series stats), index (point position). Applied after value_factor. Example: return x - first. See Value Transform. |
data_attribute
|
string | null |
Read chart data from an entity attribute array instead of history. The attribute must contain an array of objects with time and value fields. Ideal for forecast/price data (EPEX, Nordpool, weather). See Attribute Data Source. |
data_time_field
|
string | "start_time" |
Name of the time field in each array item when using data_attribute. |
data_value_field
|
string | "price_per_kwh" |
Name of the value field in each array item when using data_attribute. |
data_value_expression
|
string | null |
Compute each point's value with a safe arithmetic expression instead of reading a single data_value_field. The array element's own fields and any data_vars are in scope. Operators + - * / %, parentheses, and the functions min, max, abs, round, floor, ceil, sqrt, pow. Not JavaScript — no other variables, property access, or calls. Falls back to data_value_field when empty or invalid. See Attribute Data Source → Computed Values. |
data_vars
|
map | null |
Maps names used in data_value_expression to entity IDs (name: entity_id). Each resolves to the entity's numeric state and is re-evaluated live when that entity changes. |
data_time_unit
|
string | "iso" |
How to interpret the time field. iso = string or epoch ms (default — existing behavior). epoch_seconds / epoch_ms = Unix timestamp. month_of_year (1–12), day_of_month (1–31), day_of_year (1–366), week_of_year (1–53), hour_of_day (0–23) = numeric category — perfect for monthly summaries, day-of-year datasets, and hourly profiles without generating artificial timestamps. See Attribute Data Source → Time Unit. |
data_time_year
|
number | null |
Reference year used to anchor categorical time units (month_of_year, day_of_month, day_of_year, week_of_year). Empty = current year. (day_of_month is anchored to that year and the month of the visible window's start.) Has no effect for iso or epoch_* units. |
offset
|
string/number | 0 |
Shifts this entity backward in time by the given number of hours. Use to overlay the same sensor from different periods. 24 = yesterday, 168 = last week, 720 = last month. Also accepts a helper entity ID (e.g. input_number.my_offset) for dynamic offset — the entity's state is read as hours. See Time Offset. |
forecast_horizon
|
number | null |
For forecast sensors whose current state predicts T+N hours ahead (e.g. "Solar forecast in 1 hour"). Shifts each recorded data point forward by N hours so the value lands at its target future time on the X axis. The X axis is extended automatically to keep the shifted points visible. Independent from offset — both can be combined. See Forecast Horizon. |
datetime_format
|
string | "system" |
Deprecated — use the card-level datetime_format instead. Entity-level values still work for backward compatibility and override the card setting when present. |
fixed_value
|
boolean | false |
Draw a flat horizontal reference line at the current value instead of history |
invert
|
boolean | false |
Flips the sign of the value (×−1). On Timeline it draws bars downward from the zero line — tooltip, state row and extrema labels still show positive values; use with stacked: true for butterfly charts. Because the flip happens in the shared data pipeline it works in every chart mode — in Waterfall it makes the entity a subtraction step. Editor: per-entity → Advanced tab. See Invert Bars. |
state_map
|
list | null |
Map non-numeric states to numbers for graphing. Each entry takes a value plus optional label and color. See State Map. |