Skip to content

Icon

An icon gives an entity a recognizable visual place on the card. Use it to show an entity icon, a custom MDI icon, or an image anywhere in the layout.

Flexible Horseshoe Card can use a Home Assistant entity icon, a configured MDI icon, or an SVG, PNG, JPG, or other supported image.

Basic configuration

Add icons under layout.icons:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
entities:
  - entity: light.living_room

layout:
  icons:
    - id: light-icon
      entity_index: 0
      xpos: 50
      ypos: 50
      icon_size: 3

Without an explicit icon, Flexible Horseshoe Card uses the icon of the selected Home Assistant entity.

1
2
3
4
5
6
7
layout:
  icons:
    - id: menu-icon
      icon: mdi:dots-vertical
      xpos: 50
      ypos: 50
      icon_size: 3

A configured icon does not require an entity.

Configuration options

Field Required Default Description
xpos Yes Horizontal icon position
ypos Yes Vertical icon position
entity_index No Not set Entity whose icon and state can be used
icon No Entity icon MDI icon or url(...) SVG/image
icon_size No Relative icon size
icon_size_percent No Not set Icon size relative to the card
align No center start, center, or end
rotate No 0 Icon rotation in degrees
state_map No Not set Selects an icon based on entity state
styles No Default icon style SVG and CSS styling
color_stops No Not set Colors the icon from the entity state

Choose the icon

Set icon when you want to use a specific icon instead of the Home Assistant entity icon:

1
2
3
4
5
6
layout:
  icons:
    - icon: mdi:thermometer
      xpos: 50
      ypos: 50
      icon_size: 3

You can also configure an icon on the entity:

1
2
3
entities:
  - entity: sensor.living_room_temperature
    icon: mdi:home-thermometer

An icon configured directly on the Icon tool takes priority over the entity icon.

SVG and image files

Use url(...) to display an SVG or image instead of an MDI icon.

1
2
3
4
5
6
layout:
  icons:
    - icon: url(/local/icons/weather.svg)
      xpos: 50
      ypos: 50
      icon_size: 4

1
2
3
4
5
6
layout:
  icons:
    - icon: url(/local/images/weather.png)
      xpos: 50
      ypos: 50
      icon_size: 4

1
2
3
4
5
6
layout:
  icons:
    - icon: url(/local/images/background.jpg)
      xpos: 50
      ypos: 50
      icon_size: 4

The URL can also point to an external image:

1
2
3
4
5
6
layout:
  icons:
    - icon: url(https://example.com/images/weather.png)
      xpos: 50
      ypos: 50
      icon_size: 4

This makes the Icon tool useful for both Home Assistant icons and custom graphics.

Size and position

Position an icon with xpos and ypos.

Use icon_size for the regular relative icon size:

1
2
3
4
5
6
layout:
  icons:
    - icon: mdi:fan
      xpos: 50
      ypos: 50
      icon_size: 4

Use icon_size_percent when the icon should scale relative to the card:

1
2
3
4
5
6
layout:
  icons:
    - icon: mdi:fan
      xpos: 50
      ypos: 50
      icon_size_percent: 20

See Positioning and sizing for more about the card coordinate system.

Alignment

Use align to control how the icon is positioned around xpos:

1
2
3
4
5
- icon: mdi:thermometer
  xpos: 20
  ypos: 50
  icon_size: 3
  align: start

1
2
3
4
5
- icon: mdi:thermometer
  xpos: 50
  ypos: 50
  icon_size: 3
  align: center

1
2
3
4
5
- icon: mdi:thermometer
  xpos: 80
  ypos: 50
  icon_size: 3
  align: end

Rotate an icon

Use rotate to rotate the icon:

1
2
3
4
5
6
7
layout:
  icons:
    - icon: mdi:arrow-up
      xpos: 50
      ypos: 50
      icon_size: 3
      rotate: 90

Change the icon by state

Use state_map when different entity states should display different icons:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
entities:
  - entity: light.living_room

layout:
  icons:
    - entity_index: 0
      xpos: 50
      ypos: 50
      icon_size: 4

      state_map:
        map:
          - state: "on"
            icon: mdi:lightbulb-on

          - state: "off"
            icon: mdi:lightbulb-off

A default entry can provide a fallback when no other state matches:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
state_map:
  map:
    - state: "on"
      icon: mdi:lightbulb-on

    - state: "off"
      icon: mdi:lightbulb-off

    - state: default
      icon: mdi:lightbulb-question

Icon appearance

Use styles to change the appearance of an icon:

1
2
3
4
5
6
7
8
9
layout:
  icons:
    - icon: mdi:fan
      xpos: 50
      ypos: 50
      icon_size: 4
      styles:
        fill: var(--primary-color)
        opacity: 0.8

See Styling for the complete styling guide.

Color from an entity

When an icon is connected to an entity, color stops can change its color from the entity state:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
layout:
  icons:
    - entity_index: 0
      xpos: 50
      ypos: 50
      icon_size: 4

      show:
        item_style: colorstop

      color_stops:
        colors:
          0: green
          50: orange
          100: red

See Color stops for ranges, gradients, palettes, and interpolation.