Icon¶

The Icon tool adds a visual symbol to a card. It can use the icon Home Assistant already knows for an entity, another MDI icon, or an external SVG/image, and it can also change with the entity state.

This page shows how to choose the icon source, size and align it, rotate it, change it by state, and apply fixed or value-based colors.

Show the entity icon¶

Use the Icon tool when the Home Assistant entity icon provides a compact visual identity for the item.

1
2
3
4
5
6
7
8

entities:
  - entity: sensor.living_room_temperature  # Home Assistant entity used by this card

layout:
  icons:
    - entity_index: 0  # Use the first entity configured above
      xpos: 50  # Horizontal position; 50 = center of the card
      ypos: 50  # Vertical position; 50 = center of the card

Choose another icon¶

Override the icon when the Home Assistant default does not represent the purpose of this card clearly enough.

1
2
3
4
5
6
7
8
9

entities:
  - entity: sensor.example_1  # Entity used by this example

layout:
  icons:
    - entity_index: 0  # Use entity 0 from entities: (0 = first entity)
      xpos: 50  # Horizontal position; 50 = center of the card
      ypos: 50  # Vertical position; 50 = center of the card
      icon: mdi:thermometer  # Icon shown to the user

Use an image or SVG¶

For a Home Assistant/MDI icon, set icon to its icon name, for example mdi:thermometer. For an external SVG or image, use CSS-style url(...) syntax. A URL ending in .svg is loaded as SVG; other URLs are shown as images.

1
2
3
4
5
6

layout:
  icons:
    - xpos: 50  # Horizontal position; 50 = center of the card
      ypos: 50  # Vertical position; 50 = center of the card
      icon: url(/local/icons/temperature.svg)  # External SVG shown by this Icon tool
      icon_size_percent: 18  # Geometric icon size on the card's 100-unit scale

Keep the source in the same Icon tool so its size, position, and alignment remain together.

Change size and position¶

Adjust size and position when the icon needs to fit the surrounding text, gauge, or control.

1
2
3
4
5
6
7
8
9

entities:
  - entity: sensor.example_1  # Entity used by this example

layout:
  icons:
    - entity_index: 0  # Use entity 0 from entities: (0 = first entity)
      xpos: 50  # Horizontal position; 50 = center of the card
      ypos: 35  # Vertical position; 50 = center of the card
      icon_size: 4

Rotate the icon¶

Rotate an icon when direction itself carries meaning, such as an arrow or orientation indicator.

1
2
3
4
5
6
7
8
9

entities:
  - entity: sensor.example_1  # Entity used by this example

layout:
  icons:
    - entity_index: 0  # Use entity 0 from entities: (0 = first entity)
      xpos: 50  # Horizontal position; 50 = center of the card
      ypos: 50  # Vertical position; 50 = center of the card
      rotate: 90  # Rotate the result by 90°

Change the icon by state¶

Use state_map when different entity states should use different icons. This keeps the state-to-icon choices together with the Icon tool.

Change the icon color¶

Use styles for a fixed appearance or color_stops when the color should follow the entity value/state.

Configuration options¶

Required applies to the specific form described by that table: Yes means you need the field for that form; No means you can leave it out. Not set means the card adds no explicit value when the option is omitted.

Related¶

• Entities
• State
• Color stops
• JavaScript templates