Radial Gauge

Class: FxRadialGauge · Tag: <fx-radial-gauge> · Mixins: Animatable, GlassOverlay

The <fx-radial-gauge> component is a high-performance, responsive radial gauge designed for real-time human-machine interface (HMI) applications, aerospace cockpits, industrial dashboards, and SCADA systems.

Installation

import '@salsafx/ui';

Interactive preview of the main variants:

Needle

Triangle Needle

Clock Face

Basic Usage

Render a simple circular gauge with a label and unit. Move the slider below to update the gauge value in real-time — notice the smooth transitions!

Control Value:65

<fx-radial-gauge
    value="45"
    min="0"
    max="100"
    label="Oil Temperature"
    unit="°C"
></fx-radial-gauge>

Customizing Slots

You can customize the needle and scale by passing child elements into specific named slots:

Triangular Needle

To change the default needle to a modern aviation-grade triangular shape, use the needle slot with <fx-gauge-needle-triangle>:

<fx-radial-gauge
    value="75"
    min="0"
    max="100"
    label="Oil Pressure"
    unit="BAR"
    is-animated
    has-shell
>
    <fx-gauge-needle-triangle
        slot="needle"
        value="75"
        min="0"
        max="100"
    ></fx-gauge-needle-triangle>
</fx-radial-gauge>

Simple Scale

To use minimal simple radial scales instead of the default bold scale, use the scale slot with <fx-radial-simple-scale>:

<fx-radial-gauge
    value="40"
    min="0"
    max="100"
>
    <fx-radial-simple-scale
        slot="scale"
        value="40"
        min="0"
        max="100"
    ></fx-radial-simple-scale>
</fx-radial-gauge>

Shell Effect

The hasShell property renders a physical instrument-style background and a glass overlay. It’s enabled by default; set it to false for a flat, transparent look. It adapts automatically to cover the track whenever hasTrack is enabled. When enabled, slotted needles also receive a subtle drop shadow via their hasShadow flag.

Control Value:68

<fx-radial-gauge
    value="68"
    min="0"
    max="100"
    label="Altitude"
    unit="ft x100"
    has-shell
>
    <fx-gauge-needle-triangle
        slot="needle"
        value="68"
        min="0"
        max="100"
        style="--fx-gauge-needle-gradient-start: #a855f7; --fx-gauge-needle-gradient-end: #c084fc;"
    ></fx-gauge-needle-triangle>
</fx-radial-gauge>

Needle color is overridable via --fx-gauge-needle-gradient-start / --fx-gauge-needle-gradient-end (or --fx-gauge-needle-color). Custom glass appearance can be adjusted with --fx-glass-color and --fx-glass-opacity.

Flat

Set hasShell to false for a flat look — disabling the background fill, glass overlay, and needle shadows.

<fx-radial-gauge
    value="45"
    min="0"
    max="100"
    label="Oil Temp"
    unit="°C"
    style="
        --fx-gauge-gradient-start: #3b82f6;
        --fx-gauge-gradient-middle: #f59e0b;
        --fx-gauge-gradient-end: #ef4444;
    "
></fx-radial-gauge>

In markup, boolean false must be set via the property (element.hasShell = false) because a present has-shell attribute is always treated as true.

Colored Regions

Nest <fx-gauge-region> children to paint value bands on the dial. Omit color to assign colors from the built-in swatch sequence. Set has-region-tooltip to show the region label on hover.

<fx-radial-gauge
    value="72"
    min="0"
    max="100"
    label="Oil Temp"
    unit="°C"
    is-animated
    has-region-tooltip
>
    <fx-gauge-region from="0" to="60" label="OK"></fx-gauge-region>
    <fx-gauge-region from="60" to="80" label="Warn"></fx-gauge-region>
    <fx-gauge-region from="80" to="100" label="High"></fx-gauge-region>
</fx-radial-gauge>

Building a Clock Face

Because the dial geometry is fully configurable via startAngle and arcLength, the same component can be turned into a full 360° analog clock face instead of a tachometer-style arc. Set start-angle="0" and arc-length="360" on the gauge, its ticks, and every needle, then stack a <fx-gauge-needle> for seconds with two <fx-gauge-needle-triangle> needles for minutes and hours into the needle slot. Use the ticks’ replacements property (e.g. { 0: 12 }) to relabel the top tick from “0” to “12”.

<fx-radial-gauge
    min="0"
    max="12"
    start-angle="0"
    arc-length="360"
    has-value-display="false"
    has-track="false"
    has-shell
>
    <fx-radial-scale
        slot="scale"
        count="12"
        start-angle="0"
        arc-length="360"
        sub-divisions="5"
        min="0"
        max="12"
    ></fx-radial-scale>
    <fx-gauge-needle
        slot="needle"
        start-angle="0"
        arc-length="360"
        value="30"
        min="0"
        max="60"
    ></fx-gauge-needle>
    <fx-gauge-needle-triangle
        slot="needle"
        start-angle="0"
        arc-length="360"
        value="10"
        min="0"
        max="60"
    ></fx-gauge-needle-triangle>
    <fx-gauge-needle-triangle
        slot="needle"
        start-angle="0"
        arc-length="360"
        value="10"
        min="0"
        max="12"
        thickness="4.5"
        style="transform: scale(0.65);"
    ></fx-gauge-needle-triangle>
</fx-radial-gauge>

API Reference

Properties & Attributes

Property	Attribute	Type	Default	Description
`value`	`value`	`Number`	`0`	Current value.
`min`	`min`	`Number`	`0`	Minimum value.
`max`	`max`	`Number`	`100`	Maximum value.
`startAngle`	`start-angle`	`Number`	`-135`	Starting angle in degrees (0 is top/12 o’clock).
`arcLength`	`arc-length`	`Number`	`270`	Total sweep angle of the dial in degrees.
`isAnimated`	`is-animated`	`Boolean`	`true`	Enables fluid, hardware-accelerated transitions when the value updates.
`disabled`	`disabled`	`Boolean`	`false`	Disables the control and prevents user interaction.
`hasScaleLabels`	`has-scale-labels`	`Boolean`	`true`	Shows numeric labels on major ticks.
`hasValueDisplay`	`has-value-display`	`Boolean`	`true`	Shows the value display in the center of the gauge.
`hasTrack`	`has-track`	`Boolean`	`true`	Shows the background track arc.
`hasShell`	`has-shell`	`Boolean`	`true`	Shows the outer shell background, glass overlay, and enables needle shadows.
`hasRegionTooltip`	`has-region-tooltip`	`Boolean`	`false`	Shows a tooltip with the region `label` when hovering a colored region.
`theme`	`theme`	`String`	—	Shell look when `hasShell` is on: `silver` or `dark`. Empty follows the ThemeManager default (`silver`).
`label`	`label`	`String`	`""`	Descriptive label text (e.g., “RPM”).
`unit`	`unit`	`String`	`""`	Unit of measure text (e.g., “RPM”, “kPa”).

Slots

Name	Description
`default`	Nested `<fx-gauge-region>` value bands (`from`, `to`, optional `color`, optional `label`).
`scale`	Custom scale. Expects `<fx-radial-scale>` or `<fx-radial-simple-scale>`.
`needle`	Custom needle indicators. Expects `<fx-gauge-needle>` or `<fx-gauge-needle-triangle>`. Shadow follows the gauge `hasShell` state (`has-shadow` on each needle).
`display`	Custom center display. Expects `<fx-value-display>`.

CSS Custom Properties

Property	Default	Description
`--fx-gauge-size`	`340px`	Outer diameter width/height of the gauge.
`--fx-gauge-shell-fill`	`transparent` (`#1e293b` with `has-shell`)	Gauge shell / background fill behind the track and scale.
`--fx-gauge-track-color`	`#0f172a`	Background color of the gauge track.
`--fx-gauge-fill-color`	`url(#fx-gauge-default-gradient)`	Active bar track fill (supports colors, gradients, solid images).
`--fx-gauge-gradient-start`	`#06b6d4`	Default starting gradient color for the active bar fill.
`--fx-gauge-gradient-middle`	`#6366f1`	Default middle gradient color.
`--fx-gauge-gradient-end`	`#a855f7`	Default ending gradient color.
`--fx-gauge-needle-color`	`url(#fx-needle-default-gradient)`	Needle stroke/fill (solid color or gradient).
`--fx-gauge-needle-gradient-start`	`#f97316`	Default needle gradient at the hub.
`--fx-gauge-needle-gradient-end`	`#ef4444`	Default needle gradient toward the tip.
`--fx-glass-color`	`#ffffff`	Tint color of the glass overlay.
`--fx-glass-opacity`	`0.6`	Opacity of the glass overlay.

Object Hierarchy

classDiagram
    direction TB
    class FxElement
    class FxMeasureElement
    class FxRadialGauge

    FxElement <|-- FxMeasureElement
    FxMeasureElement <|-- FxRadialGauge : Animatable + GlassOverlay