Entity options
The entity card, the entity group card and the entity sections card describe an entity with the same keys. On the entity card they sit directly on the card; in a group or section they are the items of entities, either a plain entity id or an object. The first row below is the bare id, the second an object with the options this page explains.
Value and attribute
By default the card shows the entity state, formatted with the entity's unit. Two keys change that:
| Key | Shows |
|---|---|
attribute | an attribute of the entity, for example attribute: current_position |
value | a Jinja template ({{ … }}) or plain text; an entity is then optional |
unit, decimals (0 to 3), prefix and suffix apply to whatever is shown. Rules compare against the numeric value, so they also work on attributes and template results.
Template
Any string containing {{ }} is rendered by Home Assistant. Templates are supported for title, icon, name, secondary, color and value; a template result that looks like a number gets decimals, unit and rules like a state. unit, prefix, suffix and rule labels are plain text. Home Assistant also renders {% %} blocks; the examples on this site only evaluate {{ }} expressions.
Secondary line
secondary adds a line under the name on the entity card and the hero lead. Templates make it a status line.
Plain text
Any other string is shown as is. Useful for scene rows where the value is a verb.
Rules
rules is a list; the first entry that matches decides colour, icon, label and card tint. Write them in the order they should be tried.
| Matcher | Matches when |
|---|---|
below | the value is numeric and < below |
above | the value is numeric and >= above |
state | the state (or attribute, or value) text equals state; quote "on" / "off" |
A rule may combine below and above for a range. Numeric rules never match text, so numeric and state rules can share one list. States that no rule matches keep the entity icon and use primary, or grey for off-like states (off, closed, idle, standby, docked, not_home, disarmed, clear). An explicit color or icon on the entity always wins over the rules.
YAML anchors
Home Assistant's YAML supports anchors (&t) and aliases (*t), handy for repeating the same rules across entities.
State rules label text states, on a badge or in the secondary line.
Card tint
tint_card: true on a rule colours the whole card while that rule matches. In a group or sections card the first tinting entity wins.
Visuals
visual decides how the entity is drawn. Every visual uses the same value, rules, colour and actions; it only changes the picture. Three of them (sparkline, columns, strip) read the recorder history for the card's history window. The table lists which keys each visual reads; the sections below show them one by one.
| Visual | Draws | Options | Drawn in |
|---|---|---|---|
icon | the entity icon in a coloured circle | everywhere | |
ring | a progress ring around the icon (grid cells: around the value) | min / max | everywhere but headers |
gauge | a half-circle gauge with the value inside and min / max labels | min / max | tile, list, grid, hero |
bar | a horizontal progress bar under the value | min / max | tile, list, grid, hero |
sparkline | a smoothed line of the last hours_to_show hours | hours_to_show | tile, list, grid, hero |
columns | one bar per bucket_minutes bucket, peak highlighted | hours_to_show, bucket_minutes | tile, list, grid, hero |
badge | a coloured pill with the rule label or the value | rules[].label | everywhere |
strip | a timeline coloured by the matching rule per bucket | hours_to_show, bucket_minutes, rules | tile, list, grid, hero |
"Everywhere" includes the compact items of the row, column and table layouts; header entities draw icon and badge only. See Visuals in items and headers for what happens to the others there.
Icon
The default. The icon sits in a soft circle of the entity's colour, the value and the rule label follow. Where the icon and colour come from, in this order: a fixed icon / color on the entity, the first matching rule, the entity's own icon (or one derived from its device_class), and primary, or grey for off-like states such as off, closed, idle or not_home. Use it whenever the value itself is the message and rules only need to flag it.
The thermostat tile shows the override: a fixed icon or color on the entity wins over the rules, which then only contribute the label.
Ring
A progress ring around the icon. Progress is (value − min) / (max − min); min and max default to the entity's min / max (or min_value / max_value) attributes and otherwise to 0 and 100, so percentage sensors need no configuration. The ring is not drawn when the value is not numeric or max is not above min; the icon stays. Colour follows the rules like everywhere else.
In a grid layout the ring grows and the value moves inside it, replacing the icon. Rings also work in row, column and table items, but not in header_entities, where they show as a plain icon.
Gauge
A half-circle gauge below the name with the formatted value in the arc and min and max printed as small labels at its ends. Same scale rules as the ring: min / max from the config, else from the entity attributes, else 0 to 100. The gauge is a block visual: it needs the extra height of a tile, list row, grid cell or hero lead, and the entity card switches to rows: auto for it.
In a grid cell the gauge replaces the big value, since it already shows it.
Bar
A thin horizontal bar under the value, filled to the same (value − min) / (max − min) progress as the ring and gauge. It is the quietest way to show a level; the rule label, if any, appears as the secondary line. Like the gauge it is a block visual and needs a tile, list row, grid cell or hero lead.
History window
sparkline, columns and strip fetch the recorder history of their entity and redraw it every five minutes. Two card-level keys shape the window; they apply to every history visual on the card (or on all sections of a sections card):
| Option | Default | Description |
|---|---|---|
hours_to_show | 24 | Length of the window in hours, at least 1. Shown as a small chip in the group header and as the left label of a strip. |
bucket_minutes | 60 | Bucket size for columns and strip, at least 5. The number of buckets is hours_to_show × 60 / bucket_minutes. |
Entities without recorder history draw an empty plot. Hovering (or touching) a plot shows the value at that point and the time.
Sparkline
A smoothed line with a soft area below it and a dot at the last value, for temperatures, prices and anything else that drifts. It reads hours_to_show only: the line is sampled to the width of the card, so bucket_minutes has no effect, and the vertical scale fits the data (with 10 % padding), so min / max are ignored too. Colour comes from the current value's rule or the fixed color; the whole line takes that colour.
Columns
One bar per bucket, for quantities that come in portions: solar power, energy, rain, wind gusts. Each bar is the mean of its bucket_minutes bucket over the last hours_to_show hours; the baseline is 0 (or the lowest value if negative), the peak bucket is drawn solid and the others lighter, and hovering a bar shows its value and time. Fine buckets over a short window give a detailed profile; coarse buckets over a long window give a daily pattern.
Badge
A coloured pill instead of the plain value. The pill shows the matching rule's label, or the formatted value when no rule has a label, and takes the rule colour. Because the pill already carries the label, the badge has no secondary line unless you set secondary. It is made for states that have names (presence, appliance programs, modes) and works in items and headers too, where it stands in for the value. In header_entities the badge carries the icon inside the pill; with show_value: false, or a value that renders empty, it is just the icon in a coloured circle. See the header example on the group card.
Badges in a row layout show the pill under the name.
Strip
A timeline of the last hours_to_show hours, one block per bucket_minutes bucket, each coloured by the rule that bucket matches. On a numeric sensor a bucket is matched by its mean value; on any other entity by the last state in the bucket. rules are therefore what gives the strip its colours: a strip without rules is a single-colour bar. The current bucket has an outline, the axis reads −N h on the left and now on the right, and hovering a block shows its value or state and time.
The same on numeric sensors, colouring every hourly bucket by the range its mean falls in:
Visuals in items and headers
The row, column and table layouts show every entity as a compact item, and header_entities sit on the title line. There is no room for a block there, so items draw icon, ring and badge only, and the header line, which is smaller still, draws icon and badge only. Any other visual on such an entity falls back to icon and logs a warning in the browser console. show_icon, show_value and show_name decide what the item shows; see Item options.
Actions
tap_action, hold_action and double_tap_action accept every Home Assistant action: more-info (default for tap and hold), toggle, navigate, url, perform-action (also call-service), assist, fire-dom-event and none. Set them on the card as defaults or per entity, as an object or as a bare action name (tap_action: toggle). The card only detects the gesture; Home Assistant runs the action, so you get its confirmation dialog, haptic feedback in the companion app and any action HA adds later. confirmation asks before running; the controls never ask (use control_confirm: true for a hold to confirm) and call their own services.
perform-action takes data and target like a Home Assistant action; url opens url_path in a new tab; entity points more-info or toggle at another entity than the row shows.
Action options
| Field | Actions | Description |
|---|---|---|
action | more-info, toggle, navigate, url, perform-action, call-service, assist, fire-dom-event or none. A bare string sets action only. | |
entity | more-info, toggle | Act on this entity instead of the row's entity. |
navigation_path | navigate | Dashboard path; navigation_replace: true replaces the history entry. |
url_path | url | Opened in a new tab. |
perform_action / service | perform-action | domain.action; service is the legacy spelling. |
data / service_data | perform-action | Action data; service_data is the legacy spelling. |
target | perform-action | { entity_id, device_id, area_id }. |
pipeline_id | assist | The assist pipeline; start_listening: true starts the microphone right away. |
confirmation | all | true or { text, title, confirm_text, dismiss_text, exemptions }; Home Assistant shows its dialog, exemptions: [{ user }] skip it for those users. |
fire-dom-event passes every other key of the action to the DOM event, which is how browser_mod popups are opened: tap_action: { action: fire-dom-event, browser_mod: { service: browser_mod.popup, data: { … } } }. The docs demo only shows a toast for assist and fire-dom-event.
Item options
Row, column and table layouts and header entities show every entity as a compact item. Four keys decide what an item shows; they cascade from the card to the section to the entity.
| Option | Row | Column | Table | Header entities | Description |
|---|---|---|---|---|---|
show_name | true | true | true | false | The name, above or below the icon (table: the key) |
show_value | true | true | true | true | The value under the name (badge: the pill; a header badge without it is a circle with the icon) |
show_icon | true | true | false | true | The round icon (table: an icon column; header badge: the icon inside the pill) |
name_position | below | – | – | – | above or below the icon; rows only |
Entity options
All keys an entity accepts, grouped by what they do. "Applies to" names the visuals or layouts a key matters for; the rest apply everywhere.
Identity and value
| Option | Default | Applies to | Description |
|---|---|---|---|
entity | all | Entity id. Optional when value is plain text or a template, or for a row of your own buttons. | |
name | friendly name | all | Text or template. |
secondary | tile, hero lead | Line under the name instead of the value and label. Template allowed. | |
attribute | all | Show this attribute instead of the state (hvac_mode shows a thermostat's mode, which HA keeps in the state). | |
value | all | A template or plain text instead of the state; see Value and attribute. | |
unit | entity unit | all | Unit text after the value. |
decimals | as reported | all | 0 to 3. |
prefix / suffix | all | Text around the value. |
Look
| Option | Default | Applies to | Description |
|---|---|---|---|
visual | icon | all | icon, ring, gauge, bar, sparkline, columns, badge or strip; see Visuals. Block visuals fall back to icon in items and headers. |
icon | entity icon | all | Fixed icon that overrides rule icons. Template allowed. |
color | HA state | all | Fixed colour that overrides rule colours. Without it the entity uses Home Assistant's state colour (see the colour guide), plain sensors primary. Template allowed. |
rules | all | List of { state, below, above, color, icon, label, tint_card }, first match wins; see Rules. below and above may be numeric strings. |
Scale
| Option | Default | Applies to | Description |
|---|---|---|---|
min / max | entity min / max attributes, else 0 / 100 | ring, gauge, bar | Bounds of the progress (value − min) / (max − min). Nothing is drawn when the value is not numeric or max ≤ min. |
History
These two keys sit on the card, not on the entity, and apply to every history visual on it; see History window.
| Option | Default | Applies to | Description |
|---|---|---|---|
hours_to_show | 24 | sparkline, columns, strip | Window in hours, at least 1. |
bucket_minutes | 60 | columns, strip | Bucket size in minutes, at least 5. Sparklines ignore it. |
Controls
See Controls for what every control looks like and where it sits.
| Option | Default | Applies to | Description |
|---|---|---|---|
control | all but headers | auto (or true) picks the domain default, a name picks one, none draws nothing. control_position, control_attribute, control_step, control_options and control_confirm tune it: see Controls; control: buttons with control_options draws your own buttons. | |
toggle | false | all but headers | Deprecated alias of control: toggle. |
tap_action / hold_action / double_tap_action | card defaults | all | Per-entity overrides, see Action options. |
Items
| Option | Default | Applies to | Description |
|---|---|---|---|
show_name / show_value / show_icon | per layout | row, column, table, header | What a compact item shows, see Item options. |
name_position | below | row | above or below the icon; the other layouts ignore it. |
Every card also accepts the Home Assistant keys grid_options, visibility, layout_options, view_layout and card_mod; see Sizing in sections.