Gauge

A gauge is the dial of the gauge card, and of the energy gauge cards like self-sufficiency. It shows one value on a half circle, with the number printed in the middle. The dial adds context: where the value sits in its range, and how good or bad that is.

Use a gauge for:

• One value that lives within a known range, where the position in that range matters, like a temperature, a battery level, or a percentage
• A value with a severity, like good, warning, or bad

Don't use a gauge for:

• A level inside a settings row or a list. Use a bar, it takes far less room.
• A value without a meaningful minimum and maximum. The dial has nothing to show then.

1. Track: the empty half circle, the full range from min to max
2. Value arc: the filled part of the track, up to the value
3. Levels: optional colored segments of the track
4. Needle: in needle mode, replaces the value arc and points at the value
5. Value text: the formatted value and unit, or the label of the current level, in the middle

The default. The arc fills up to the value. The dial color can carry meaning: the success, warning, or error color, based on where the value is. Without a color set, the filled part of the dial has no color. Use the info color when the value has no good or bad.

In the needle version, the dial shows a needle instead of a filled arc, and can be colored in segments, called levels. Each level starts at its own value and runs up to the next one. This shows the whole scale at once, so people see both the value and how close it is to the next segment.

A level can have a label. When the value falls in that segment, the label replaces the number in the middle of the gauge. Use it when a word says more than the number, like Low or High.

If the first level does not start at the minimum, the gauge adds a segment in the info color from the minimum up to the first level.

• The gauge is not interactive. It has no hover, focus, pressed, or disabled state.
• When the value changes, the arc or needle moves to the new position in 1 second, with an ease curve.
• A value below the minimum or above the maximum is shown at the start or end of the dial. The text still shows the real value.
• The value text scales to fit the space inside the dial: at most 55% of the width and 40% of the height of the gauge.
• A percent sign gets the spacing that fits the language of the user. Any other unit is shown after a space.
• The value text is always laid out left to right, also in a right to left language.

The gauge is an SVG that scales with its width. The sizes below are in SVG units, on a drawing that is 100 units wide and 55 units high.

The gauge is not focusable and has no keyboard interaction.

A screen reader can read the value and unit as text. The dial itself, and the severity it shows, has no text alternative: severity is shown through color only. The value text is the part that does not depend on color.

The gauge has no role and no ARIA attributes. The value and unit are SVG text.

• Bar: a compact level for rows and lists
• Controls: when the value can be changed
• Gauge card: the card built on this dial
• Color: the severity colors

The element is <ha-gauge>. Give it a width; the height follows.

<ha-gauge
  value="21"
  min="0"
  max="40"
  label="°C"
  style="width: 200px; --gauge-color: var(--success-color)"
></ha-gauge>

The value is formatted with the locale of the user, so set the locale property from hass.locale.

• value: the current value. Defaults to 0.
• min: the start of the scale. Defaults to 0.
• max: the end of the scale. Defaults to 100.
• label: the unit, shown after the value.
• needle: shows a needle instead of a filled arc.
• levels: a JSON array of segments, each with a level, a stroke color, and an optional label. If the first level does not start at min, the gauge adds an info colored segment from min.

These can only be set as properties:

• locale: the locale data used to format the value.
• valueText: text to show instead of the formatted value. The gauge card uses it to show the state as formatted by Home Assistant.
• formatOptions: Intl.NumberFormatOptions for formatting the value.

• --gauge-color: the color of the filled arc. Not used in needle mode.
• --primary-background-color: the empty part of the dial.
• --primary-text-color: the value text, and the needle.

Source: src/components/ha-gauge.ts