Horseshoe value and progress¶

A Horseshoe needs a value range and a rule for turning the current entity value into visible progress along its path. The scale defines where values belong, while the state/progress settings define how the active part of the path is drawn.

This page shows how to set the range, use linear or spline mapping, change progress width and direction, and handle positive/negative or mapped-state displays.

Set the value range¶

The scale range tells the Horseshoe where the minimum and maximum values sit on its path, so the current value can be placed correctly.

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

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

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

Change the visible thickness¶

Use the scale width for the base path and the state width for the current-value progress:

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

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

layout:
  horseshoes:
    - entity_index: 0  # Use entity 0 from entities: (0 = first entity)
      radius: 42  # Distance from the center to the Horseshoe path

      horseshoe_scale:
        min: 0  # Value at the start of the scale
        max: 100  # Value at the end of the scale
        width: 6  # Thickness of the base scale path

      horseshoe_state:
        width: 12  # Thickness of the active value/progress path

Show progress normally¶

bar_mode: normal shows the value from the start of the scale toward the end. This is the normal choice for values such as percentage, temperature, storage, or load.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

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

layout:
  horseshoes:
    - entity_index: 0  # Use entity 0 from entities: (0 = first entity)
      bar_mode: normal  # Choose where progress starts and in which direction it grows
      horseshoe_scale:
        min: 0  # Value at the start of the scale
        max: 100  # Value at the end of the scale

Show positive and negative values¶

Use a bidirectional mode when values can move in both directions around zero, such as importing/exporting power or charging/discharging.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

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

layout:
  horseshoes:
    - entity_index: 0  # Use entity 0 from entities: (0 = first entity)
      bar_mode: bidirectional  # Choose where progress starts and in which direction it grows

      horseshoe_scale:
        min: -5000  # Value at the start of the scale
        max: 5000  # Value at the end of the scale

• normal — progress grows from the scale minimum toward the maximum.
• bidirectional — progress grows away from zero. The zero position can be set with zero_ratio; when it is omitted the card derives the position from the configured scale.
• bidirectional_symmetrical — zero is in the center and positive/negative progress grows away from that center.
• bidirectional_linear — positive and negative progress grows away from zero with a linear distribution along each side.
• absolute — the visible progress shows the magnitude from the start of the Horseshoe path. The signed entity value is still available for the displayed state and color selection. horseshoe_scale.min must be <= 0, horseshoe_scale.max must be > 0, and zero_ratio must not be set.

zero_ratio applies to bidirectional, bidirectional_symmetrical, and bidirectional_linear; do not set it with normal or absolute.

Use a non-linear scale¶

Use horseshoe_scale.type when equal value differences should not always take equal visual space. A spline scale can emphasize part of the range while keeping the complete value range visible.

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

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

layout:
  horseshoes:
    - entity_index: 0  # Use entity 0 from entities: (0 = first entity)
      horseshoe_scale:
        min: 0  # Value at the start of the scale
        max: 14  # Value at the end of the scale
        type: spline
        spline:
          anchors:
            - value: 5      # The value 5...
              position: 0.2 # ...is placed at 20% of the visible path
            - value: 8      # The value 8...
              position: 0.8 # ...is placed at 80% of the visible path

Show named states as a level¶

Use the Horseshoe state modes together with state_map when textual states such as low, medium, and high should occupy positions or levels on the path.

Use stringstate_mode when only the segment for the current mapped state should be active. Use stringstate_level when the current segment and every earlier/lower mapped segment should be active. Both modes use the order of the entries in state_map.map; keep the matching label configuration with the same state mapping so the visible text follows the active segment.

Add a background behind the gauge¶

A background path can make the complete gauge range remain visible even when the active progress covers only part of it.

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

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

layout:
  horseshoes:
    - entity_index: 0  # Use entity 0 from entities: (0 = first entity)
      horseshoe_scale: {}  # Required scale block; uses the default 0–100 linear scale

      show:
        horseshoe_background: fixed

      horseshoe_background:
        width: 16  # Thickness of the background path
        color: var(--divider-color)

show.horseshoe_background accepts these values:

• none — hides the background. This is the default.
• fixed — uses the configured background color/styles across the complete path.
• colorstopsegments — divides the background into hard color-stop sections.
• lineargradient — spreads the configured colors evenly across the complete path.
• colorstopgradient — positions the gradient colors according to their configured scale values.

The tick and label background selectors use the same five values. Their own page explains the corresponding horseshoe_tickmarks.background and horseshoe_labels.background settings.

Choose how progress is colored¶

Use show.horseshoe_style to choose how the active progress path is colored. The default is fixed.

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

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

layout:
  horseshoes:
    - entity_index: 0  # Use entity 0 from entities: (0 = first entity)
      horseshoe_scale:
        min: 0
        max: 100
      show:
        horseshoe_style: colorstopgradient  # Place gradient colors at their configured scale values
      color_stops:
        colors:
          - value: 0
            color: green
          - value: 40
            color: orange
          - value: 100
            color: red

Choose how the base scale is colored¶

Use show.scale_style for the complete base scale behind the active progress.

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

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

layout:
  horseshoes:
    - entity_index: 0
      horseshoe_scale:
        min: 0
        max: 100
      show:
        scale_style: colorstopsegments  # Show hard color ranges across the complete base scale
      color_stops:
        colors:
          - value: 0
            color: green
          - value: 50
            color: orange
          - value: 100
            color: red

Animate value changes¶

Use the supported Horseshoe animation settings when the progress should animate between values. For state-triggered CSS animation of complete items, see Animations.

Configuration reference¶

Linear scale¶

A linear scale is the default. Equal differences in value use equal distances on the Horseshoe.

Spline scale¶

Use a spline only when part of the value range needs more or less visible space than another part.

Scale appearance¶

Current-value progress¶

Color selectors¶

Bar modes¶

Related documentation¶

• Horseshoe overview
• Markers
• Tick marks and labels
• Color stops