State icon

Every entity in Home Assistant has an icon, and the icon follows its state. A door sensor shows an open door when the door is open, and a closed one when it is closed. A light that is on can show its color and brightness. People read the state of their home from these icons, often before they read any text.

Two components do this work:

• The state icon picks the icon for an entity in its state. It has no color of its own.
• The state badge puts that icon in a 40px round badge, and adds the color. It is the icon at the start of an entity row, in the more info dialog header, in pickers, and in many other places.

Use them for:

• Every place where you show an entity with an icon

Don't use them for:

• An icon that is not about an entity. Use a plain icon.
• A value with a label in a compact pill. Use a badge, with a state icon in its icon slot.

1. Badge: the 40px container of the state badge, round by default. It shows the entity picture as its background when there is one.
2. Icon: the state icon inside it, colored by the badge. It is hidden when a picture is shown.

The state icon is just the icon, in the color of its surroundings. The state badge adds the 40px container, the state color, and pictures.

By default only lights are colored. With state colors on, other entities get state colors too. With a theme color or any other color, that color is used while the entity is active. With colors off, nothing is colored. See how the color is picked.

The state icon goes through these steps, and uses the first icon it finds:

1. The icon set on the component itself, for example from a card configuration.
2. The icon people set for the entity in its settings.
3. The icon attribute in the state of the entity.
4. The icon the integration defines for this entity and state, in its icon translations.
5. A built-in icon for a few domains whose icon depends on more than the state, like the sun, updates, and device trackers.
6. The default icon of the domain, for this device class and state. For example, a binary sensor with the door device class has a different icon for open and closed.
7. When nothing else matches, a fallback icon for the domain, or a bookmark icon for unknown domains.

The icons in steps 4 and 6 come from Home Assistant, which loads them on demand. Until they are loaded, the component shows nothing.

You can ask for the icon of a state the entity is not in. The cover toggle in the more info dialog does this for its open and closed buttons: it shows the icon of the blinds in the state the button would set.

By default, the state badge only colors lights. Every other entity gets the default icon color, whatever its state. Turn on state colors to color by state for other entities too. Where people configure a card or a row, they choose this with the Show state color option.

With state colors on, the color comes from the theme. For each entity, the badge looks for the most specific color the theme defines, in this order:

1. --state-<domain>-<device class>-<state>-color, like --state-binary_sensor-door-on-color.
2. --state-<domain>-<state>-color, like --state-person-home-color.
3. --state-<domain>-active-color or --state-<domain>-inactive-color.
4. --state-active-color or --state-inactive-color.

Whether a state counts as active depends on the domain: on, open, home, and playing are active. Off, closed, not home, and locked are not. Inactive entities keep the default icon color in a badge. Only domains that have state colors get them; a sensor, for example, keeps the default color. Battery sensors are the exception: their color follows the battery level.

On top of that:

• A light with a color shows that color, and a dimmer light shows a darker icon.
• A thermostat takes the color of what it is doing right now, like heating or cooling, not of the mode it is set to.
• An unavailable entity is shown in the unavailable color, whatever its domain. With a custom color, or without state colors, it keeps the default color instead.

Instead of state colors, the badge can use one color, like a theme color such as red or primary, or any CSS color. That color is used while the entity is active, and the default color while it is not. Colors can also be turned off completely, also for lights.

When an entity has a picture, like a person with a profile picture or a media player with album art, the state badge shows the picture instead of the icon. Media players and cameras get slightly rounded corners, other pictures a circle. Update entities get square corners. An icon set on the badge wins over the picture.

• Use these components whenever you show an entity. When you pick an icon yourself, you skip the icon that people or integrations set, and the icon does not change with the state.
• Where people configure a card or a row, let them choose state colors with the Show state color option.

The state badge is not focusable on its own. When the page around it makes it focusable, it shows a 2px border in the divider color, or a divider color background when it shows an icon.

The icon adds nothing to what a screen reader reads, so the state must be in text nearby, like the state in an entity row. The state icon can show the formatted state as a native tooltip on hover.

• The SVG inside the icon is hidden from screen readers.
• With state-title, ha-state-icon gets the formatted state as its title.
• state-badge has no role.

• Badge: the dashboard badge, which shows a state icon
• Entity picker: shows state icons for its entities
• Color: the theme colors behind state colors

The element is <state-badge>.

html`<state-badge .stateObj=${stateObj} color="state"></state-badge>`

Attributes:

• color: state to color by state, none for no color, or a theme color or CSS color to use while the entity is active. Without it, only lights are colored.

These can only be set as properties:

• stateObj: the state object of the entity.
• overrideIcon: an icon name, like mdi:sofa, to use instead of the icon of the entity.
• overrideImage: a picture URL to use instead of the icon or the entity picture.
• stateColor: the older way to set the color, as true or false. color takes precedence over it.

Without a stateObj, overrideIcon, or overrideImage, the badge shows a yellow alert icon.

Styling:

• --state-icon-color: the default icon color. The theme sets it.
• --state-badge-border-radius: defaults to 50%.
• --state-badge-with-image-border-radius: for an entity picture. Defaults to 50%.
• --state-badge-with-media-image-border-radius: for a media player or camera picture. Defaults to 8%.

The badge is 40 by 40 pixels. Set width and height to change that.

Source: src/components/entity/state-badge.ts

The element is <ha-state-icon>. It takes the color of its surroundings, like any icon.

html`<ha-state-icon .stateObj=${stateObj}></ha-state-icon>`
html`<ha-state-icon .stateObj=${stateObj} .stateValue=${"closed"}></ha-state-icon>`

Attributes:

• icon: an icon name, like mdi:sofa, to use instead of the icon of the entity.
• state-title: sets the title of the icon to the formatted state, so it shows as a native tooltip.

These can only be set as properties:

• stateObj: the state object of the entity.
• stateValue: a state to show the icon for, instead of the current state of the entity.

Styling:

• --mdc-icon-size: the icon size. Defaults to 24px.

Source: src/components/ha-state-icon.ts