Horseshoe gauges¶

A Horseshoe is a gauge that maps an entity value onto an arc or another path. The path provides the visual scale, while the current value can be shown as progress, a marker, labels, colors, or a combination of those elements.

This page builds the basic Horseshoe, explains its position, radius, arc, and value range, and introduces the other Horseshoe topics you can add afterward.

Add a basic Horseshoe¶

A basic Horseshoe needs an entity and a value scale; the remaining settings mainly change its geometry and presentation.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

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

layout:
  horseshoes:
    - 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
      radius: 42  # Distance from the center to the Horseshoe path
      arc_degrees: 260  # Draw 260° of the full 360° circle

      horseshoe_scale:
        min: 0  # Value at the start of the scale
        max: 100  # Value at the end of the scale

radius sets the size of the normal circular Horseshoe. arc_degrees controls how much of the circle is used. min and max define the value range.

The normal position settings are xpos and ypos. Existing configurations can also use horseshoe_position with xpos/ypos or cx/cy; those values supply the same Horseshoe center when the top-level position is omitted.

Change how the value is shown¶

The current value normally grows from the start of the scale. Bidirectional modes instead let positive and negative values grow from zero, which is useful for values such as power flow, deviation, or temperature difference. You can also change the scale mapping and the thickness of the base and active paths.

See Value and progress for the complete choices.

Add colors¶

Use value colors when the gauge should communicate meaning such as normal, warning, and critical at a glance.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

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

layout:
  horseshoes:
    - 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
      radius: 42  # Distance from the center to the Horseshoe path
      arc_degrees: 260  # Draw 260° of the full 360° circle

      horseshoe_scale:
        min: 0  # Value at the start of the scale
        max: 100  # Value at the end of the scale

      color_stops:
        colors:
          0: green
          60: orange
          90: red

      show:
        horseshoe_style: colorstopinterpolated

See Color stops for the shared color system.

Add tick marks and labels¶

Add ticks and labels when the viewer needs to read approximate values from the gauge rather than only see its progress.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

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

layout:
  horseshoes:
    - 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
      radius: 42  # Distance from the center to the Horseshoe path
      tickmarks_radius: 43  # Put the ticks 1 unit outside the Horseshoe radius of 42

      horseshoe_scale:
        min: 0  # Value at the start of the scale
        max: 100  # Value at the end of the scale

      show:
        tickmarks: true
        labels_at: ticks_major  # Choose which scale values receive a label

      horseshoe_tickmarks:
        ticks_major:
          ticksize: 10  # Draw a major tick every 10 scale units

      horseshoe_labels:
        offset: 12  # Distance of the labels from the Horseshoe radius

Mark the current value¶

Add a marker when you want a point, triangle, icon, or center pointer to show exactly where the current value is.

See Markers.

Use another path shape¶

The Horseshoe does not have to be circular. It can follow a line, rectangle, polygon, wave, spiral, or infinity path.

See Path shapes.

Visual guide¶

The Horseshoe can combine several visible parts:

• the base scale/path;
• current-value progress;
• an optional background;
• tick marks;
• labels;
• a current-value marker.

One annotated overview image is enough here to identify those parts. The detail pages explain how to use each one.

Configuration reference¶

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 documentation¶

• Value and progress
• Markers
• Tick marks and labels
• Path shapes
• Color stops