Horseshoe scale and state¶

The scale defines the value range and base geometry of the horseshoe. The state layer shows the current value within that range. Styling them separately makes it possible to keep the scale subtle while giving the active value more visual emphasis.

Scale configuration¶

Use horseshoe_scale to define the value range and appearance of the base arc.

1
2
3
4
5
6
7
8
9

horseshoe_scale:
  min: 0
  max: 100
  type: linear
  width: 6
  linecap: round
  styles:
    - fill: var(--divider-color)
    - opacity: 0.5

When color_stops.scales.default defines a minimum and maximum, the horseshoe uses that range automatically. Explicit horseshoe_scale.min or horseshoe_scale.max values override the corresponding color-stop values. If neither is configured, the range falls back to 0 through 100.

A linear scale is the best choice for most gauges. Use a spline scale only when the spacing needs to follow a verified spline definition. Tick marks, labels, and the state arc all use the same mapping, so they remain aligned.

State configuration¶

Use horseshoe_state to control the active value layer.

1
2
3
4
5
6

horseshoe_state:
  width: 12
  mode: value
  linecap: round
  styles:
    - fill: var(--primary-color)

State modes¶

The selected mode determines whether the current state appears as one continuous arc or as a set of discrete segments.

String-state modes require a state map. Labels can use the same mapping, which keeps the visible text synchronized with the active segment.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

horseshoe_state:
  mode: stringstate_level
  state_map:
    map:
      - state: low
        value: 1
      - state: medium
        value: 2
      - state: high
        value: 3

Normal and bidirectional bars¶

Configure bar_mode on the horseshoe item itself because it affects the geometry shared by both the scale and the state.

When the scale range crosses zero, the default zero_ratio is calculated from horseshoe_scale.min and horseshoe_scale.max. Set zero_ratio manually only when the visual zero position should differ from the numeric ratio.

Absolute bars¶

bar_mode: absolute keeps the entity value signed for state text and color-stop selection, but draws its magnitude from the physical start of the horseshoe. Do not configure zero_ratio for this mode.

A 0..max scale shares one magnitude range between both signs. With min: 0 and max: 15, both -5 and +5 fill one third of the arc. Signed color stops remain independent, so those values can still use different colors.

A scale that crosses zero gives each sign its own complete arc. With min: -10 and max: 40, -5 fills half of the negative branch while +5 fills one eighth of the positive branch. The active branch also supplies scale/background colors, ticks, and magnitude labels. At exactly zero, the positive branch is active.

absolute uses the configured linear, spline, or splineorg mapping independently for each branch and supports every continuous horseshoe color style.

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

bar_mode: absolute

horseshoe_scale:
  min: -10
  max: 40
  type: linear

color_stops:
  - -10: green
  - 0: gray
  - 5: orange
  - 40: red

Background layer¶

horseshoe_background adds an optional arc behind the full gauge. Enable it with show.horseshoe_background, then configure its geometry and appearance separately.

1
2
3
4
5
6
7
8
9

show:
  horseshoe_background: fixed

horseshoe_background:
  width: 16
  offset: 0
  styles:
    - fill: var(--divider-color)
    - opacity: 0.2

State colors¶

Use show.horseshoe_style to control how the horseshoe is colored.

colorstopgradient uses every configured color stop. For example, with blue at 0, yellow at 50, and red at 100, the gradient runs from blue through yellow to red. The horseshoe reveals that gradient up to the current value.

For a normal bar, lineargradient distributes every configured color evenly over the active horseshoe. The numeric distance between color-stop values does not affect their visual spacing.

For a bidirectional bar, lineargradient creates separate gradients for negative and positive values. Each side distributes its applicable colors evenly between the outer scale value and zero. Add a color stop at 0 to control the center color, or let FHS calculate it from the surrounding stops.

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

bar_mode: bidirectional

show:
  horseshoe_style: lineargradient

horseshoe_scale:
  min: -5
  max: 5

color_stops:
  colors:
    -5: red
    0: gray
    5: green

In this example, negative values use a gray-to-red gradient, while positive values use a gray-to-green gradient. When the scale extends below or above zero, define at least one color stop on each side that should display a gradient.

The same color stops can also be reused by backgrounds and tick marks. See Color Stops for the complete syntax.

Animation¶

State changes can animate from the previous value to the new one. Configure this behavior under horseshoe_state.animation. General animation concepts and reusable definitions are covered in Animations.

Animation affects only the transition between valid states. The scale range, state map, and color-stop settings still determine the final geometry and color.

Related documentation¶

• Horseshoe Gauges
• Horseshoe Tick Marks and Labels
• Color Stops
• Color Filters