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 fills the gauge face with the same shell color as the potentiometer bezel (#1e293b, overridable via --fx-gauge-shell-fill) and adds a subtle glossy glass frame on top — a soft highlight near the top plus a thin rim light tracing the full outer edge. 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 get a compact drop shadow (0 2px 4px at 0.55 opacity) 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). Fine-tune the glass tint and intensity with --fx-glass-color and --fx-glass-opacity.

Flat

Set hasShell to false for a flat look — no shell fill, glass overlay, or needle drop shadow.

<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.

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, glossy glass overlay, and enables needle shadows.
`label`	`label`	`String`	`""`	Descriptive label text (e.g., “RPM”).
`unit`	`unit`	`String`	`""`	Unit of measure text (e.g., “RPM”, “kPa”).

Slots

Name	Description
`default`	Optional slot for nested contents.
`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 shell highlight and rim light.
`--fx-glass-opacity`	`0.6`	Overall opacity of the shell glass overlay (highlight + rim).

Object Hierarchy

classDiagram
    direction TB
    class FxElement
    class FxMeasureElement
    class FxRadialGauge

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