# Gauge

Read a metric's current state within a defined range.

Canonical: https://chart.syidax.com/docs/components/gauge/

<a id="overview"></a>

## sy-gauge-chart

Use for values with a clear range, such as target completion, capacity, or speed.

Show trends over time in a separate chart. Explain out-of-range values and the meaning of boundaries.

Base chart tier: Community. Features such as additional renderers and custom branding have separate entitlement requirements.

| Input | Data description |
| --- | --- |
| `value` | The current measurement. |
| `min` | The start of the measurement range. |
| `max` | The end of the measurement range. |
| `variant` | The gauge style, such as solid or dial. |

- [Run in Components](https://chart.syidax.com/charts/gauge) — Change options and view framework-specific code
- [Shared installation and integration](https://chart.syidax.com/docs/getting-started.md)

<a id="example"></a>

## Complete implementation example

```html
<div id="chart-container" style="width: 100%; min-width: 0;"></div>

<script type="module">
  import { defineCustomElement as define0 } from '@syidax/advanced/components/sy-gauge-chart.js';
  define0();

  const specs = [
    {
      "id": "example-chart",
      "tag": "sy-gauge-chart",
      "props": {
        "engine": "standard",
        "value": 80,
        "min": 0,
        "max": 200,
        "variant": "dial",
        "unit": "km/h",
        "bandThickness": 14,
        "plotBands": [
          {
            "from": 0,
            "to": 120,
            "color": "#16a34a"
          },
          {
            "from": 120,
            "to": 160,
            "color": "#f59e0b"
          },
          {
            "from": 160,
            "to": 200,
            "color": "#dc2626"
          }
        ],
        "width": 640,
        "height": 360,
        "brandPosition": "bottom-right",
        "brandLogo": ""
      }
    }
  ];
  const container = document.querySelector('#chart-container');
  const elements = specs.map(({ tag, id, props }) => {
    const element = document.createElement(tag);
    element.id = id;
    Object.assign(element, props);
    element.setAttribute('aria-label', 'gauge example chart');
    return element;
  });
  container.replaceChildren(...elements);
  const chart = elements.at(-1);
  const onEvent = event => {
    console.log('valueChange', event.detail);
  };
  chart.addEventListener('valueChange', onEvent);
  const observer = new ResizeObserver(([entry]) => {
    const width = Math.max(160, Math.floor(entry.contentRect.width));
    elements.forEach(element => { element.width = width; });
  });
  observer.observe(container);

  // In an SPA, call this function when the view is disposed.
  function disposeChart() {
    observer.disconnect();
    chart.removeEventListener('valueChange', onEvent);
    container.replaceChildren();
  }
</script>
```

<a id="props"></a>

## Properties

<a id="property-value"></a>

### value

The current measurement.

| Item | Value |
| --- | --- |
| JavaScript property | `value` |
| HTML attribute | `value` |
| Type | `number` |
| Default | `0` |

<a id="property-min"></a>

### min

The start of the measurement range.

| Item | Value |
| --- | --- |
| JavaScript property | `min` |
| HTML attribute | `min` |
| Type | `number` |
| Default | `0` |

<a id="property-max"></a>

### max

The end of the measurement range.

| Item | Value |
| --- | --- |
| JavaScript property | `max` |
| HTML attribute | `max` |
| Type | `number` |
| Default | `100` |

<a id="property-needles"></a>

### needles

Multi-needle override (dial variant). When set + non-empty, drives the dial instead of `value`.

| Item | Value |
| --- | --- |
| JavaScript property | `needles` |
| HTML attribute | Pass objects, arrays, and callbacks as JavaScript properties |
| Type | `GaugeNeedleSpec[]` |
| Default | `undefined` |

undefined means this property was not explicitly set. The effective value may depend on the chart type and other settings.

- [GaugeNeedleSpec](https://chart.syidax.com/docs/types/GaugeNeedleSpec.md) — Type definition

<a id="property-width"></a>

### width

Chart width in pixels. If the container width changes, update width from a ResizeObserver.

| Item | Value |
| --- | --- |
| JavaScript property | `width` |
| HTML attribute | `width` |
| Type | `number` |
| Default | `320` |

<a id="property-height"></a>

### height

Chart height in pixels. Allow space for axes, titles, and the legend.

| Item | Value |
| --- | --- |
| JavaScript property | `height` |
| HTML attribute | `height` |
| Type | `number` |
| Default | `280` |

<a id="property-brandLogo"></a>

### brandLogo

The default is the Syidax symbol and wordmark. With the Pro chart.branding entitlement, set none to remove it or provide a PNG, JPEG, or WebP data URL to replace it.

| Item | Value |
| --- | --- |
| JavaScript property | `brandLogo` |
| HTML attribute | `brand-logo` |
| Type | `string` |
| Default | `undefined` |

undefined means this property was not explicitly set. The effective value may depend on the chart type and other settings.

<a id="property-brandPosition"></a>

### brandPosition

The corner where the logo is anchored. Community and Pro both support all four corners, using the same position on screen and in image exports.

| Item | Value |
| --- | --- |
| JavaScript property | `brandPosition` |
| HTML attribute | `brand-position` |
| Type | `'top-left' \| 'top-right' \| 'bottom-left' \| 'bottom-right'` |
| Default | `'bottom-right'` |
| Allowed values | `top-left`, `top-right`, `bottom-left`, `bottom-right` |

<a id="property-variant"></a>

### variant

The gauge style, such as solid or dial.

| Item | Value |
| --- | --- |
| JavaScript property | `variant` |
| HTML attribute | `variant` |
| Type | `GaugeChartVariant` |
| Default | `'dial'` |
| Allowed values | `solid`, `dial`, `activity`, `vuMeter`, `speedometer`, `clock` |

- [GaugeChartVariant](https://chart.syidax.com/docs/types/GaugeChartVariant.md) — Type definition

<a id="property-startAngle"></a>

### startAngle

Set as an HTML attribute or JavaScript property. type: number.

| Item | Value |
| --- | --- |
| JavaScript property | `startAngle` |
| HTML attribute | `start-angle` |
| Type | `number` |
| Default | `-150` |

<a id="property-endAngle"></a>

### endAngle

Set as an HTML attribute or JavaScript property. type: number.

| Item | Value |
| --- | --- |
| JavaScript property | `endAngle` |
| HTML attribute | `end-angle` |
| Type | `number` |
| Default | `150` |

<a id="property-size"></a>

### size

Pass as a JavaScript property. type: number | string.

| Item | Value |
| --- | --- |
| JavaScript property | `size` |
| HTML attribute | Pass objects, arrays, and callbacks as JavaScript properties |
| Type | `number \| string` |
| Default | `undefined` |

undefined means this property was not explicitly set. The effective value may depend on the chart type and other settings.

<a id="property-centerX"></a>

### centerX

Pass as a JavaScript property. type: number | string.

| Item | Value |
| --- | --- |
| JavaScript property | `centerX` |
| HTML attribute | Pass objects, arrays, and callbacks as JavaScript properties |
| Type | `number \| string` |
| Default | `undefined` |

undefined means this property was not explicitly set. The effective value may depend on the chart type and other settings.

<a id="property-centerY"></a>

### centerY

Pass as a JavaScript property. type: number | string.

| Item | Value |
| --- | --- |
| JavaScript property | `centerY` |
| HTML attribute | Pass objects, arrays, and callbacks as JavaScript properties |
| Type | `number \| string` |
| Default | `undefined` |

undefined means this property was not explicitly set. The effective value may depend on the chart type and other settings.

<a id="property-innerRadius"></a>

### innerRadius

Solid-variant inner radius. Number = px; `'%'` = fraction of outerRadius.

| Item | Value |
| --- | --- |
| JavaScript property | `innerRadius` |
| HTML attribute | Pass objects, arrays, and callbacks as JavaScript properties |
| Type | `number \| string` |
| Default | `undefined` |

undefined means this property was not explicitly set. The effective value may depend on the chart type and other settings.

<a id="property-thickness"></a>

### thickness

Band / solid-ring thickness in px. Wins over innerRadius for the solid variant.

| Item | Value |
| --- | --- |
| JavaScript property | `thickness` |
| HTML attribute | `thickness` |
| Type | `number` |
| Default | `undefined` |

undefined means this property was not explicitly set. The effective value may depend on the chart type and other settings.

<a id="property-rings"></a>

### rings

Activity-variant rings (property-only). Each ring has its OWN `value`/`max` (Move 500 kcal, Exercise 30 min…). Absent → the variant falls back to `needles` (shared chart max) or the scalar `value` (one ring).

| Item | Value |
| --- | --- |
| JavaScript property | `rings` |
| HTML attribute | Pass objects, arrays, and callbacks as JavaScript properties |
| Type | `GaugeActivityRingSpec[]` |
| Default | `undefined` |

undefined means this property was not explicitly set. The effective value may depend on the chart type and other settings.

- [GaugeActivityRingSpec](https://chart.syidax.com/docs/types/GaugeActivityRingSpec.md) — Type definition

<a id="property-time"></a>

### time

Clock-variant time. `'now'`/unset keeps the face ticking live (1 s interval, cleaned up on disconnect); `'HH:MM'`/`'HH:MM:SS'` freezes it.

| Item | Value |
| --- | --- |
| JavaScript property | `time` |
| HTML attribute | `time` |
| Type | `string` |
| Default | `undefined` |

undefined means this property was not explicitly set. The effective value may depend on the chart type and other settings.

<a id="property-showSeconds"></a>

### showSeconds

Clock-variant second hand (thin, red).

| Item | Value |
| --- | --- |
| JavaScript property | `showSeconds` |
| HTML attribute | `show-seconds` |
| Type | `boolean` |
| Default | `true` |

<a id="property-color"></a>

### color

Set as an HTML attribute or JavaScript property. type: string.

| Item | Value |
| --- | --- |
| JavaScript property | `color` |
| HTML attribute | `color` |
| Type | `string` |
| Default | `'#2563eb'` |

<a id="property-colors"></a>

### colors

Needle palette (multi-needle). Per-needle `color` always wins.

| Item | Value |
| --- | --- |
| JavaScript property | `colors` |
| HTML attribute | Pass objects, arrays, and callbacks as JavaScript properties |
| Type | `ReadonlyArray<string>` |
| Default | `undefined` |

undefined means this property was not explicitly set. The effective value may depend on the chart type and other settings.

<a id="property-stops"></a>

### stops

Solid-variant colour stops (0..1 along min..max). Progress colour interpolates between them.

| Item | Value |
| --- | --- |
| JavaScript property | `stops` |
| HTML attribute | Pass objects, arrays, and callbacks as JavaScript properties |
| Type | `GaugeColorStop[]` |
| Default | `undefined` |

undefined means this property was not explicitly set. The effective value may depend on the chart type and other settings.

- [GaugeColorStop](https://chart.syidax.com/docs/types/GaugeColorStop.md) — Type definition

<a id="property-needleShape"></a>

### needleShape

Allowed values: needle, arrow, line, wedge. Default: 'needle'.

| Item | Value |
| --- | --- |
| JavaScript property | `needleShape` |
| HTML attribute | `needle-shape` |
| Type | `GaugeNeedleShape` |
| Default | `'needle'` |
| Allowed values | `needle`, `arrow`, `line`, `wedge` |

- [GaugeNeedleShape](https://chart.syidax.com/docs/types/GaugeNeedleShape.md) — Type definition

<a id="property-needleLength"></a>

### needleLength

Pass as a JavaScript property. type: number | string.

| Item | Value |
| --- | --- |
| JavaScript property | `needleLength` |
| HTML attribute | Pass objects, arrays, and callbacks as JavaScript properties |
| Type | `number \| string` |
| Default | `'88%'` |

<a id="property-needleRearLength"></a>

### needleRearLength

Pass as a JavaScript property. type: number | string.

| Item | Value |
| --- | --- |
| JavaScript property | `needleRearLength` |
| HTML attribute | Pass objects, arrays, and callbacks as JavaScript properties |
| Type | `number \| string` |
| Default | `'14%'` |

<a id="property-needleWidth"></a>

### needleWidth

Set as an HTML attribute or JavaScript property. type: number.

| Item | Value |
| --- | --- |
| JavaScript property | `needleWidth` |
| HTML attribute | `needle-width` |
| Type | `number` |
| Default | `8` |

<a id="property-pivotRadius"></a>

### pivotRadius

Set as an HTML attribute or JavaScript property. type: number.

| Item | Value |
| --- | --- |
| JavaScript property | `pivotRadius` |
| HTML attribute | `pivot-radius` |
| Type | `number` |
| Default | `7` |

<a id="property-pivotColor"></a>

### pivotColor

Set as an HTML attribute or JavaScript property. type: string.

| Item | Value |
| --- | --- |
| JavaScript property | `pivotColor` |
| HTML attribute | `pivot-color` |
| Type | `string` |
| Default | `'#1f2937'` |

<a id="property-plotBands"></a>

### plotBands

Coloured zones — an array, or `'auto'` to split the axis by % of max.

| Item | Value |
| --- | --- |
| JavaScript property | `plotBands` |
| HTML attribute | Pass objects, arrays, and callbacks as JavaScript properties |
| Type | `GaugePlotBand[] \| 'auto'` |
| Default | `undefined` |
| Literals in the type | `auto` |

undefined means this property was not explicitly set. The effective value may depend on the chart type and other settings.

- [GaugePlotBand](https://chart.syidax.com/docs/types/GaugePlotBand.md) — Type definition

<a id="property-bandThickness"></a>

### bandThickness

Set as an HTML attribute or JavaScript property. type: number.

| Item | Value |
| --- | --- |
| JavaScript property | `bandThickness` |
| HTML attribute | `band-thickness` |
| Type | `number` |
| Default | `14` |

<a id="property-bandTrackColor"></a>

### bandTrackColor

The 'empty' track behind plot bands — the un-zoned part of the axis.

| Item | Value |
| --- | --- |
| JavaScript property | `bandTrackColor` |
| HTML attribute | `band-track-color` |
| Type | `string` |
| Default | `'#eef2f7'` |

<a id="property-rounded"></a>

### rounded

Set as an HTML attribute or JavaScript property. type: boolean.

| Item | Value |
| --- | --- |
| JavaScript property | `rounded` |
| HTML attribute | `rounded` |
| Type | `boolean` |
| Default | `true` |

<a id="property-trackColor"></a>

### trackColor

Set as an HTML attribute or JavaScript property. type: string.

| Item | Value |
| --- | --- |
| JavaScript property | `trackColor` |
| HTML attribute | `track-color` |
| Type | `string` |
| Default | `'#e5e7eb'` |

<a id="property-showTicks"></a>

### showTicks

Set as an HTML attribute or JavaScript property. type: boolean.

| Item | Value |
| --- | --- |
| JavaScript property | `showTicks` |
| HTML attribute | `show-ticks` |
| Type | `boolean` |
| Default | `true` |

<a id="property-tickInterval"></a>

### tickInterval

Allowed values: auto. Default: 'auto'.

| Item | Value |
| --- | --- |
| JavaScript property | `tickInterval` |
| HTML attribute | Pass objects, arrays, and callbacks as JavaScript properties |
| Type | `number \| 'auto'` |
| Default | `'auto'` |
| Literals in the type | `auto` |

<a id="property-minorTicks"></a>

### minorTicks

Set as an HTML attribute or JavaScript property. type: number.

| Item | Value |
| --- | --- |
| JavaScript property | `minorTicks` |
| HTML attribute | `minor-ticks` |
| Type | `number` |
| Default | `4` |

<a id="property-tickLength"></a>

### tickLength

Set as an HTML attribute or JavaScript property. type: number.

| Item | Value |
| --- | --- |
| JavaScript property | `tickLength` |
| HTML attribute | `tick-length` |
| Type | `number` |
| Default | `9` |

<a id="property-minorTickLength"></a>

### minorTickLength

Set as an HTML attribute or JavaScript property. type: number.

| Item | Value |
| --- | --- |
| JavaScript property | `minorTickLength` |
| HTML attribute | `minor-tick-length` |
| Type | `number` |
| Default | `6` |

<a id="property-tickWidth"></a>

### tickWidth

Set as an HTML attribute or JavaScript property. type: number.

| Item | Value |
| --- | --- |
| JavaScript property | `tickWidth` |
| HTML attribute | `tick-width` |
| Type | `number` |
| Default | `2` |

<a id="property-minorTickWidth"></a>

### minorTickWidth

Set as an HTML attribute or JavaScript property. type: number.

| Item | Value |
| --- | --- |
| JavaScript property | `minorTickWidth` |
| HTML attribute | `minor-tick-width` |
| Type | `number` |
| Default | `1` |

<a id="property-tickColor"></a>

### tickColor

Set as an HTML attribute or JavaScript property. type: string.

| Item | Value |
| --- | --- |
| JavaScript property | `tickColor` |
| HTML attribute | `tick-color` |
| Type | `string` |
| Default | `'#94a3b8'` |

<a id="property-showTickLabels"></a>

### showTickLabels

Set as an HTML attribute or JavaScript property. type: boolean.

| Item | Value |
| --- | --- |
| JavaScript property | `showTickLabels` |
| HTML attribute | `show-tick-labels` |
| Type | `boolean` |
| Default | `true` |

<a id="property-tickLabelDistance"></a>

### tickLabelDistance

Set as an HTML attribute or JavaScript property. type: number.

| Item | Value |
| --- | --- |
| JavaScript property | `tickLabelDistance` |
| HTML attribute | `tick-label-distance` |
| Type | `number` |
| Default | `7` |

<a id="property-tickLabelColor"></a>

### tickLabelColor

Set as an HTML attribute or JavaScript property. type: string.

| Item | Value |
| --- | --- |
| JavaScript property | `tickLabelColor` |
| HTML attribute | `tick-label-color` |
| Type | `string` |
| Default | `'#64748b'` |

<a id="property-tickLabelFontSize"></a>

### tickLabelFontSize

Set as an HTML attribute or JavaScript property. type: number.

| Item | Value |
| --- | --- |
| JavaScript property | `tickLabelFontSize` |
| HTML attribute | `tick-label-font-size` |
| Type | `number` |
| Default | `11` |

<a id="property-tickLabelFormat"></a>

### tickLabelFormat

Set as an HTML attribute or JavaScript property. type: string.

| Item | Value |
| --- | --- |
| JavaScript property | `tickLabelFormat` |
| HTML attribute | `tick-label-format` |
| Type | `string` |
| Default | `undefined` |

undefined means this property was not explicitly set. The effective value may depend on the chart type and other settings.

<a id="property-showValue"></a>

### showValue

Set as an HTML attribute or JavaScript property. type: boolean.

| Item | Value |
| --- | --- |
| JavaScript property | `showValue` |
| HTML attribute | `show-value` |
| Type | `boolean` |
| Default | `true` |

<a id="property-valueDisplay"></a>

### valueDisplay

Print the raw `value` or its `percent` of the axis (gauges use both).

| Item | Value |
| --- | --- |
| JavaScript property | `valueDisplay` |
| HTML attribute | `value-display` |
| Type | `GaugeValueDisplay` |
| Default | `'value'` |
| Allowed values | `percent`, `value` |

- [GaugeValueDisplay](https://chart.syidax.com/docs/types/GaugeValueDisplay.md) — Type definition

<a id="property-valueFormat"></a>

### valueFormat

Set as an HTML attribute or JavaScript property. type: string.

| Item | Value |
| --- | --- |
| JavaScript property | `valueFormat` |
| HTML attribute | `value-format` |
| Type | `string` |
| Default | `undefined` |

undefined means this property was not explicitly set. The effective value may depend on the chart type and other settings.

<a id="property-valueColor"></a>

### valueColor

Set as an HTML attribute or JavaScript property. type: string.

| Item | Value |
| --- | --- |
| JavaScript property | `valueColor` |
| HTML attribute | `value-color` |
| Type | `string` |
| Default | `'#0f172a'` |

<a id="property-valueFontSize"></a>

### valueFontSize

Set as an HTML attribute or JavaScript property. type: number.

| Item | Value |
| --- | --- |
| JavaScript property | `valueFontSize` |
| HTML attribute | `value-font-size` |
| Type | `number` |
| Default | `26` |

<a id="property-unit"></a>

### unit

Set as an HTML attribute or JavaScript property. type: string.

| Item | Value |
| --- | --- |
| JavaScript property | `unit` |
| HTML attribute | `unit` |
| Type | `string` |
| Default | `undefined` |

undefined means this property was not explicitly set. The effective value may depend on the chart type and other settings.

<a id="property-centerText"></a>

### centerText

Set as an HTML attribute or JavaScript property. type: string.

| Item | Value |
| --- | --- |
| JavaScript property | `centerText` |
| HTML attribute | `center-text` |
| Type | `string` |
| Default | `undefined` |

undefined means this property was not explicitly set. The effective value may depend on the chart type and other settings.

<a id="property-centerSubtext"></a>

### centerSubtext

Set as an HTML attribute or JavaScript property. type: string.

| Item | Value |
| --- | --- |
| JavaScript property | `centerSubtext` |
| HTML attribute | `center-subtext` |
| Type | `string` |
| Default | `undefined` |

undefined means this property was not explicitly set. The effective value may depend on the chart type and other settings.

<a id="property-chartTitle"></a>

### chartTitle

The title inside the chart. Explain the data's unit and meaning alongside it.

| Item | Value |
| --- | --- |
| JavaScript property | `chartTitle` |
| HTML attribute | `chart-title` |
| Type | `string` |
| Default | `undefined` |

undefined means this property was not explicitly set. The effective value may depend on the chart type and other settings.

<a id="property-chartSubtitle"></a>

### chartSubtitle

The subtitle inside the chart.

| Item | Value |
| --- | --- |
| JavaScript property | `chartSubtitle` |
| HTML attribute | `chart-subtitle` |
| Type | `string` |
| Default | `undefined` |

undefined means this property was not explicitly set. The effective value may depend on the chart type and other settings.

<a id="property-tooltipShow"></a>

### tooltipShow

Whether to display the built-in tooltip.

| Item | Value |
| --- | --- |
| JavaScript property | `tooltipShow` |
| HTML attribute | `tooltip-show` |
| Type | `boolean` |
| Default | `true` |

<a id="property-tooltipFormat"></a>

### tooltipFormat

Pass as a JavaScript property. type: (detail: GaugeChartPointerEventDetail) => string.

| Item | Value |
| --- | --- |
| JavaScript property | `tooltipFormat` |
| HTML attribute | Pass objects, arrays, and callbacks as JavaScript properties |
| Type | `(detail: GaugeChartPointerEventDetail) => string` |
| Default | `undefined` |

undefined means this property was not explicitly set. The effective value may depend on the chart type and other settings.

- [GaugeChartPointerEventDetail](https://chart.syidax.com/docs/types/GaugeChartPointerEventDetail.md) — Type definition

<a id="property-enableMouseTracking"></a>

### enableMouseTracking

Set as an HTML attribute or JavaScript property. type: boolean.

| Item | Value |
| --- | --- |
| JavaScript property | `enableMouseTracking` |
| HTML attribute | `enable-mouse-tracking` |
| Type | `boolean` |
| Default | `true` |

<a id="property-tooltip"></a>

### tooltip

Rich tooltip configuration object — the dial-flavoured counterpart to the cartesian / pie `.tooltip` API. Enables `trigger` (hover/click/hover-click), `openMode` (single/multiple pinned), `connector`, `draggable`, `interactive` action buttons, custom `format`/`html`/`style`/`className`/`side` and fixed sizing. When set it takes precedence over the flat `tooltip-show` / `tooltipFormat` props (which stay for back-compat). Property-only — assign the object, not an attribute.

| Item | Value |
| --- | --- |
| JavaScript property | `tooltip` |
| HTML attribute | Pass objects, arrays, and callbacks as JavaScript properties |
| Type | `GaugeChartTooltipInput` |
| Default | `undefined` |
| Literals in the type | `auto`, `off` |

undefined means this property was not explicitly set. The effective value may depend on the chart type and other settings.

- [GaugeChartTooltipInput](https://chart.syidax.com/docs/types/GaugeChartTooltipInput.md) — Type definition

<a id="property-legend"></a>

### legend

Whether to show a legend for series or items.

| Item | Value |
| --- | --- |
| JavaScript property | `legend` |
| HTML attribute | `legend` |
| Type | `boolean` |
| Default | `false` |

<a id="property-legendPosition"></a>

### legendPosition

Where the legend is positioned.

| Item | Value |
| --- | --- |
| JavaScript property | `legendPosition` |
| HTML attribute | `legend-position` |
| Type | `GaugeChartLegendPosition` |
| Default | `'bottom'` |
| Allowed values | `top`, `bottom`, `left`, `right` |

- [GaugeChartLegendPosition](https://chart.syidax.com/docs/types/GaugeChartLegendPosition.md) — Type definition

<a id="property-legendItems"></a>

### legendItems

Pass as a JavaScript property. type: LegendItem[].

| Item | Value |
| --- | --- |
| JavaScript property | `legendItems` |
| HTML attribute | Pass objects, arrays, and callbacks as JavaScript properties |
| Type | `LegendItem[]` |
| Default | `undefined` |

undefined means this property was not explicitly set. The effective value may depend on the chart type and other settings.

- [LegendItem](https://chart.syidax.com/docs/types/LegendItem.md) — Type definition

<a id="property-animated"></a>

### animated

Whether to animate initial display and data changes.

| Item | Value |
| --- | --- |
| JavaScript property | `animated` |
| HTML attribute | `animate` |
| Type | `boolean` |
| Default | `false` |

<a id="property-animationDuration"></a>

### animationDuration

Animation duration in milliseconds.

| Item | Value |
| --- | --- |
| JavaScript property | `animationDuration` |
| HTML attribute | `animation-duration` |
| Type | `number` |
| Default | `900` |

<a id="property-animationEasing"></a>

### animationEasing

Allowed values: linear, ease-out, ease-in, ease-in-out, analog. Default: 'analog'.

| Item | Value |
| --- | --- |
| JavaScript property | `animationEasing` |
| HTML attribute | `animation-easing` |
| Type | `GaugeChartEasing` |
| Default | `'analog'` |
| Allowed values | `linear`, `ease-out`, `ease-in`, `ease-in-out`, `analog` |

- [GaugeChartEasing](https://chart.syidax.com/docs/types/GaugeChartEasing.md) — Type definition

<a id="property-animationType"></a>

### animationType

Allowed values: initial, update. Default: undefined.

| Item | Value |
| --- | --- |
| JavaScript property | `animationType` |
| HTML attribute | `animation-type` |
| Type | `GaugeChartAnimationType` |
| Default | `undefined` |
| Allowed values | `initial`, `update` |

undefined means this property was not explicitly set. The effective value may depend on the chart type and other settings.

- [GaugeChartAnimationType](https://chart.syidax.com/docs/types/GaugeChartAnimationType.md) — Type definition

<a id="property-analogDamping"></a>

### analogDamping

`analog` damping (1..n) for long sweeps — LOWER = bigger overshoot + more wobbles, higher = calmer. Short updates are auto-damped calmer.

| Item | Value |
| --- | --- |
| JavaScript property | `analogDamping` |
| HTML attribute | `analog-damping` |
| Type | `number` |
| Default | `5` |

<a id="property-analogFrequency"></a>

### analogFrequency

`analog` swing frequency (1..n) — higher = more wobbles packed into the settle.

| Item | Value |
| --- | --- |
| JavaScript property | `analogFrequency` |
| HTML attribute | `analog-frequency` |
| Type | `number` |
| Default | `18` |

<a id="property-analogOvershootAngle"></a>

### analogOvershootAngle

How far past the scale ends the needle may overshoot, in degrees (visible at min/max).

| Item | Value |
| --- | --- |
| JavaScript property | `analogOvershootAngle` |
| HTML attribute | `analog-overshoot-angle` |
| Type | `number` |
| Default | `14` |

<a id="property-streamSource"></a>

### streamSource

A stream source for live data. Check the contract for the specific type.

| Item | Value |
| --- | --- |
| JavaScript property | `streamSource` |
| HTML attribute | Pass objects, arrays, and callbacks as JavaScript properties |
| Type | `GaugeChartStreamSource` |
| Default | `undefined` |

undefined means this property was not explicitly set. The effective value may depend on the chart type and other settings.

- [GaugeChartStreamSource](https://chart.syidax.com/docs/types/GaugeChartStreamSource.md) — Type definition

<a id="property-streamWindow"></a>

### streamWindow

The streaming data range to keep visible.

| Item | Value |
| --- | --- |
| JavaScript property | `streamWindow` |
| HTML attribute | `stream-window` |
| Type | `number` |
| Default | `undefined` |

undefined means this property was not explicitly set. The effective value may depend on the chart type and other settings.

<a id="property-streamMax"></a>

### streamMax

The maximum number of streaming data points to retain.

| Item | Value |
| --- | --- |
| JavaScript property | `streamMax` |
| HTML attribute | `stream-max` |
| Type | `number` |
| Default | `undefined` |

undefined means this property was not explicitly set. The effective value may depend on the chart type and other settings.

<a id="property-engine"></a>

### engine

Renderer selection: auto, standard, or pro. Engine selection is separate from permission to use a Pro chart type.

| Item | Value |
| --- | --- |
| JavaScript property | `engine` |
| HTML attribute | `engine` |
| Type | `GaugeChartEngineMode` |
| Default | `'auto'` |
| Allowed values | `auto`, `standard`, `pro` |

- [GaugeChartEngineMode](https://chart.syidax.com/docs/types/GaugeChartEngineMode.md) — Type definition

<a id="property-proThreshold"></a>

### proThreshold

Set as an HTML attribute or JavaScript property. type: number.

| Item | Value |
| --- | --- |
| JavaScript property | `proThreshold` |
| HTML attribute | `pro-threshold` |
| Type | `number` |
| Default | `50_000` |

<a id="property-unavailable"></a>

### unavailable

Allowed values: fallback, error, throw. Default: 'fallback'.

| Item | Value |
| --- | --- |
| JavaScript property | `unavailable` |
| HTML attribute | `unavailable` |
| Type | `GaugeChartUnavailableBehaviour` |
| Default | `'fallback'` |
| Allowed values | `fallback`, `error`, `throw` |

- [GaugeChartUnavailableBehaviour](https://chart.syidax.com/docs/types/GaugeChartUnavailableBehaviour.md) — Type definition

<a id="events"></a>

## Events

<a id="event-rendered"></a>

### rendered

Emits rendering results in detail when chart drawing completes.

Event name: `rendered`. Names are case-sensitive. Read the payload from `detail` on `CustomEvent<GaugeChartRenderResult & { tier: GaugeChartEngineTier }>`.

```javascript
chart.addEventListener('rendered', event => {
  console.log(event.detail); // GaugeChartRenderResult & { tier: GaugeChartEngineTier }
});
```

- [GaugeChartRenderResult](https://chart.syidax.com/docs/types/GaugeChartRenderResult.md) — Type definition
- [GaugeChartEngineTier](https://chart.syidax.com/docs/types/GaugeChartEngineTier.md) — Type definition

<a id="event-gaugeClick"></a>

### gaugeClick

CustomEvent.detail type: GaugeChartPointerEventDetail. Event names are case-sensitive.

Event name: `gaugeClick`. Names are case-sensitive. Read the payload from `detail` on `CustomEvent<GaugeChartPointerEventDetail>`.

```javascript
chart.addEventListener('gaugeClick', event => {
  console.log(event.detail); // GaugeChartPointerEventDetail
});
```

- [GaugeChartPointerEventDetail](https://chart.syidax.com/docs/types/GaugeChartPointerEventDetail.md) — Type definition

<a id="event-gaugeHover"></a>

### gaugeHover

CustomEvent.detail type: GaugeChartPointerEventDetail | null. Event names are case-sensitive.

Event name: `gaugeHover`. Names are case-sensitive. Read the payload from `detail` on `CustomEvent<GaugeChartPointerEventDetail | null>`.

```javascript
chart.addEventListener('gaugeHover', event => {
  console.log(event.detail); // GaugeChartPointerEventDetail | null
});
```

- [GaugeChartPointerEventDetail](https://chart.syidax.com/docs/types/GaugeChartPointerEventDetail.md) — Type definition

<a id="event-pointContextMenu"></a>

### pointContextMenu

CustomEvent.detail type: ChartPointContextMenuEventDetail<GaugeChartPointerEventDetail>. Event names are case-sensitive.

Event name: `pointContextMenu`. Names are case-sensitive. Read the payload from `detail` on `CustomEvent<ChartPointContextMenuEventDetail<GaugeChartPointerEventDetail>>`.

```javascript
chart.addEventListener('pointContextMenu', event => {
  console.log(event.detail); // ChartPointContextMenuEventDetail<GaugeChartPointerEventDetail>
});
```

- [ChartPointContextMenuEventDetail](https://chart.syidax.com/docs/types/ChartPointContextMenuEventDetail.md) — Type definition
- [GaugeChartPointerEventDetail](https://chart.syidax.com/docs/types/GaugeChartPointerEventDetail.md) — Type definition

<a id="event-valueChange"></a>

### valueChange

CustomEvent.detail type: { value: number; fraction: number }. Event names are case-sensitive.

Event name: `valueChange`. Names are case-sensitive. Read the payload from `detail` on `CustomEvent<{ value: number; fraction: number }>`.

```javascript
chart.addEventListener('valueChange', event => {
  console.log(event.detail); // { value: number; fraction: number }
});
```

<a id="event-legendItemClick"></a>

### legendItemClick

CustomEvent.detail type: { index: number; needleId: string; label: string; disabled: boolean }. Event names are case-sensitive.

Event name: `legendItemClick`. Names are case-sensitive. Read the payload from `detail` on `CustomEvent<{ index: number; needleId: string; label: string; disabled: boolean }>`.

```javascript
chart.addEventListener('legendItemClick', event => {
  console.log(event.detail); // { index: number; needleId: string; label: string; disabled: boolean }
});
```

<a id="event-needleToggled"></a>

### needleToggled

CustomEvent.detail type: { index: number; needleId: string; disabled: boolean }. Event names are case-sensitive.

Event name: `needleToggled`. Names are case-sensitive. Read the payload from `detail` on `CustomEvent<{ index: number; needleId: string; disabled: boolean }>`.

```javascript
chart.addEventListener('needleToggled', event => {
  console.log(event.detail); // { index: number; needleId: string; disabled: boolean }
});
```

<a id="event-appended"></a>

### appended

CustomEvent.detail type: { count: number }. Event names are case-sensitive.

Event name: `appended`. Names are case-sensitive. Read the payload from `detail` on `CustomEvent<{ count: number }>`.

```javascript
chart.addEventListener('appended', event => {
  console.log(event.detail); // { count: number }
});
```

<a id="event-windowSlid"></a>

### windowSlid

CustomEvent.detail type: { dropped: number }. Event names are case-sensitive.

Event name: `windowSlid`. Names are case-sensitive. Read the payload from `detail` on `CustomEvent<{ dropped: number }>`.

```javascript
chart.addEventListener('windowSlid', event => {
  console.log(event.detail); // { dropped: number }
});
```

<a id="event-chartAnimationStart"></a>

### chartAnimationStart

CustomEvent.detail type: void. Event names are case-sensitive.

Event name: `chartAnimationStart`. Names are case-sensitive. Read the payload from `detail` on `CustomEvent<void>`.

```javascript
chart.addEventListener('chartAnimationStart', event => {
  console.log(event.detail); // void
});
```

<a id="event-chartAnimationEnd"></a>

### chartAnimationEnd

CustomEvent.detail type: void. Event names are case-sensitive.

Event name: `chartAnimationEnd`. Names are case-sensitive. Read the payload from `detail` on `CustomEvent<void>`.

```javascript
chart.addEventListener('chartAnimationEnd', event => {
  console.log(event.detail); // void
});
```

<a id="event-chartAnimationInterrupted"></a>

### chartAnimationInterrupted

CustomEvent.detail type: void. Event names are case-sensitive.

Event name: `chartAnimationInterrupted`. Names are case-sensitive. Read the payload from `detail` on `CustomEvent<void>`.

```javascript
chart.addEventListener('chartAnimationInterrupted', event => {
  console.log(event.detail); // void
});
```

<a id="event-tooltipShow"></a>

### tooltipShow

Whether to display the built-in tooltip.

Event name: `tooltipShow`. Names are case-sensitive. Read the payload from `detail` on `CustomEvent<GaugeChartTooltipShowEventDetail>`.

```javascript
chart.addEventListener('tooltipShow', event => {
  console.log(event.detail); // GaugeChartTooltipShowEventDetail
});
```

- [GaugeChartTooltipShowEventDetail](https://chart.syidax.com/docs/types/GaugeChartTooltipShowEventDetail.md) — Type definition

<a id="event-tooltipHide"></a>

### tooltipHide

CustomEvent.detail type: void. Event names are case-sensitive.

Event name: `tooltipHide`. Names are case-sensitive. Read the payload from `detail` on `CustomEvent<void>`.

```javascript
chart.addEventListener('tooltipHide', event => {
  console.log(event.detail); // void
});
```

<a id="event-tooltipAction"></a>

### tooltipAction

CustomEvent.detail type: GaugeChartTooltipActionEventDetail. Event names are case-sensitive.

Event name: `tooltipAction`. Names are case-sensitive. Read the payload from `detail` on `CustomEvent<GaugeChartTooltipActionEventDetail>`.

```javascript
chart.addEventListener('tooltipAction', event => {
  console.log(event.detail); // GaugeChartTooltipActionEventDetail
});
```

- [GaugeChartTooltipActionEventDetail](https://chart.syidax.com/docs/types/GaugeChartTooltipActionEventDetail.md) — Type definition

<a id="methods"></a>

## Methods

<a id="method-redraw"></a>

### redraw

Redraw the chart using its current data and options. Inspect the rendered result after the returned Promise resolves.

```typescript
redraw(): Promise<GaugeChartRenderResult>
```

Return type: `Promise<GaugeChartRenderResult>`. Call the method after element registration and await its Promise result.

- [GaugeChartRenderResult](https://chart.syidax.com/docs/types/GaugeChartRenderResult.md) — Type definition

<a id="method-getActiveTier"></a>

### getActiveTier

An asynchronous method. Check the argument and return types below.

```typescript
getActiveTier(): Promise<GaugeChartEngineTier>
```

Return type: `Promise<GaugeChartEngineTier>`. Call the method after element registration and await its Promise result.

- [GaugeChartEngineTier](https://chart.syidax.com/docs/types/GaugeChartEngineTier.md) — Type definition

<a id="method-getValue"></a>

### getValue

The dB value of a cell (`null` when empty or outside the grid).

```typescript
getValue(): Promise<number>
```

Return type: `Promise<number>`. Call the method after element registration and await its Promise result.

<a id="method-setValue"></a>

### setValue

Set the primary value (animates when `animated`).

```typescript
setValue(value: number): Promise<void>
```

| Arguments | Type | Required |
| --- | --- | --- |
| `value` | `number` | Required |

Return type: `Promise<void>`. Call the method after element registration and await its Promise result.

<a id="method-addNeedle"></a>

### addNeedle

Gauge-only — add a needle (dial variant).

```typescript
addNeedle(needle: GaugeNeedleSpec, opts?: { insertAt?: number }): Promise<number>
```

| Arguments | Type | Required |
| --- | --- | --- |
| `needle` | `GaugeNeedleSpec` | Required |
| `opts` | `{ insertAt?: number }` | Optional |

Return type: `Promise<number>`. Call the method after element registration and await its Promise result.

- [GaugeNeedleSpec](https://chart.syidax.com/docs/types/GaugeNeedleSpec.md) — Type definition

<a id="method-removeNeedle"></a>

### removeNeedle

Gauge-only — remove a needle by id or index.

```typescript
removeNeedle(idOrIndex: string | number): Promise<boolean>
```

| Arguments | Type | Required |
| --- | --- | --- |
| `idOrIndex` | `string \| number` | Required |

Return type: `Promise<boolean>`. Call the method after element registration and await its Promise result.

<a id="method-setRings"></a>

### setRings

Replace the activity ring set (animates per ring when `animated`).

```typescript
setRings(rings: GaugeActivityRingSpec[]): Promise<void>
```

| Arguments | Type | Required |
| --- | --- | --- |
| `rings` | `GaugeActivityRingSpec[]` | Required |

Return type: `Promise<void>`. Call the method after element registration and await its Promise result.

- [GaugeActivityRingSpec](https://chart.syidax.com/docs/types/GaugeActivityRingSpec.md) — Type definition

<a id="method-setRingValue"></a>

### setRingValue

Update ONE activity ring's value by id, name, or index (animates when `animated`).

```typescript
setRingValue(idOrIndex: string | number, value: number): Promise<boolean>
```

| Arguments | Type | Required |
| --- | --- | --- |
| `idOrIndex` | `string \| number` | Required |
| `value` | `number` | Required |

Return type: `Promise<boolean>`. Call the method after element registration and await its Promise result.

<a id="method-updateNeedle"></a>

### updateNeedle

Gauge-only — patch a needle.

```typescript
updateNeedle(idOrIndex: string | number, patch: Partial<GaugeNeedleSpec>): Promise<boolean>
```

| Arguments | Type | Required |
| --- | --- | --- |
| `idOrIndex` | `string \| number` | Required |
| `patch` | `Partial<GaugeNeedleSpec>` | Required |

Return type: `Promise<boolean>`. Call the method after element registration and await its Promise result.

- [GaugeNeedleSpec](https://chart.syidax.com/docs/types/GaugeNeedleSpec.md) — Type definition

<a id="method-appendPoint"></a>

### appendPoint

Append one value to the stream. Check the argument type and the licensing requirements for streaming.

```typescript
appendPoint(value: number): Promise<void>
```

| Arguments | Type | Required |
| --- | --- | --- |
| `value` | `number` | Required |

Return type: `Promise<void>`. Call the method after element registration and await its Promise result.

<a id="method-appendBatch"></a>

### appendBatch

Append multiple values to the stream. Check the argument type and the licensing requirements for streaming.

```typescript
appendBatch(values: ReadonlyArray<number>): Promise<void>
```

| Arguments | Type | Required |
| --- | --- | --- |
| `values` | `ReadonlyArray<number>` | Required |

Return type: `Promise<void>`. Call the method after element registration and await its Promise result.

<a id="method-shift"></a>

### shift

Drop the oldest streamed categories (the `data` boxes are not the stream).

```typescript
shift(count?: number): Promise<void>
```

| Arguments | Type | Required |
| --- | --- | --- |
| `count` | `number` | Optional |

Return type: `Promise<void>`. Call the method after element registration and await its Promise result.

<a id="method-replace"></a>

### replace

Swap the streamed set (`replace([])` clears it); the base `values` never leave. Without `chart.streaming` the dies upsert into the base like a batch (quietly: no `appended`, no `binChanged`, as a ring replace).

```typescript
replace(values: ReadonlyArray<number>): Promise<void>
```

| Arguments | Type | Required |
| --- | --- | --- |
| `values` | `ReadonlyArray<number>` | Required |

Return type: `Promise<void>`. Call the method after element registration and await its Promise result.

<a id="method-getStreamSource"></a>

### getStreamSource

The stream session's source (Chart Pro): like the stream methods it waits for a license still being confirmed.

```typescript
getStreamSource(): Promise<GaugeChartStreamSource | undefined>
```

Return type: `Promise<GaugeChartStreamSource | undefined>`. Call the method after element registration and await its Promise result.

- [GaugeChartStreamSource](https://chart.syidax.com/docs/types/GaugeChartStreamSource.md) — Type definition

<a id="method-setAnimation"></a>

### setAnimation

An asynchronous method. Check the argument and return types below.

```typescript
setAnimation(options: { duration?: number; easing?: GaugeChartEasing; enabled?: boolean; type?: GaugeChartAnimationType }): Promise<void>
```

| Arguments | Type | Required |
| --- | --- | --- |
| `options` | `{ duration?: number; easing?: GaugeChartEasing; enabled?: boolean; type?: GaugeChartAnimationType }` | Required |

Return type: `Promise<void>`. Call the method after element registration and await its Promise result.

- [GaugeChartEasing](https://chart.syidax.com/docs/types/GaugeChartEasing.md) — Type definition
- [GaugeChartAnimationType](https://chart.syidax.com/docs/types/GaugeChartAnimationType.md) — Type definition

<a id="method-pauseAnimation"></a>

### pauseAnimation

Pause the current animation.

```typescript
pauseAnimation(): Promise<void>
```

Return type: `Promise<void>`. Call the method after element registration and await its Promise result.

<a id="method-resumeAnimation"></a>

### resumeAnimation

Resume a paused animation.

```typescript
resumeAnimation(): Promise<void>
```

Return type: `Promise<void>`. Call the method after element registration and await its Promise result.

<a id="method-replayAnimation"></a>

### replayAnimation

Replay the initial sweep from min → value(s). No-op when animation is off / reduced.

```typescript
replayAnimation(): Promise<void>
```

Return type: `Promise<void>`. Call the method after element registration and await its Promise result.

<a id="method-hitTest"></a>

### hitTest

The box under a host-local CSS point (the nearest slot, within half a pitch), or null.

```typescript
hitTest(cssX: number, cssY: number): Promise<GaugeChartPointerEventDetail | null>
```

| Arguments | Type | Required |
| --- | --- | --- |
| `cssX` | `number` | Required |
| `cssY` | `number` | Required |

Return type: `Promise<GaugeChartPointerEventDetail | null>`. Call the method after element registration and await its Promise result.

- [GaugeChartPointerEventDetail](https://chart.syidax.com/docs/types/GaugeChartPointerEventDetail.md) — Type definition

<a id="method-showTooltip"></a>

### showTooltip

Open the value tooltip programmatically at the primary value (needle 0, or the scalar `value`). Anchors on the dial along the value's angle.

```typescript
showTooltip(): Promise<GaugeChartPointerEventDetail | null>
```

Return type: `Promise<GaugeChartPointerEventDetail | null>`. Call the method after element registration and await its Promise result.

- [GaugeChartPointerEventDetail](https://chart.syidax.com/docs/types/GaugeChartPointerEventDetail.md) — Type definition

<a id="method-showTooltipAtValue"></a>

### showTooltipAtValue

Gauge analogue of pie's `showTooltipAtSlice` — compute the pointer detail at `value`'s angle on the dial and open the tooltip there.

```typescript
showTooltipAtValue(value: number): Promise<GaugeChartPointerEventDetail | null>
```

| Arguments | Type | Required |
| --- | --- | --- |
| `value` | `number` | Required |

Return type: `Promise<GaugeChartPointerEventDetail | null>`. Call the method after element registration and await its Promise result.

- [GaugeChartPointerEventDetail](https://chart.syidax.com/docs/types/GaugeChartPointerEventDetail.md) — Type definition

<a id="method-hideTooltip"></a>

### hideTooltip

Close the currently visible tooltip.

```typescript
hideTooltip(): Promise<void>
```

Return type: `Promise<void>`. Call the method after element registration and await its Promise result.

<a id="method-getEngineStatus"></a>

### getEngineStatus

Requested engine vs what runs, and why (CHART-ADD-08): always Standard (this type has no WebGPU renderer); read without side effects, never consults the license.

```typescript
getEngineStatus(): Promise<ChartEngineStatus>
```

Return type: `Promise<ChartEngineStatus>`. Call the method after element registration and await its Promise result.

- [ChartEngineStatus](https://chart.syidax.com/docs/types/ChartEngineStatus.md) — Type definition