Car Gauge API

Quick Start

A pure JavaScript canvas gauge library with spring-damper needle physics. No dependencies, no build step required for usage.

// HTML: <div id="my-gauge" style="width:200px;height:200px"></div>
import { Gauge } from './src/index.js';

const gauge = new Gauge(document.getElementById('my-gauge'), {
  min: 0, max: 100, label: 'SPEED', units: 'MPH'
});
gauge.setValue(60);

Constructor

new Gauge(element, config)

• element — An HTMLElement. The gauge appends a <canvas> child inside it.
• config — A preset name string (e.g. 'speed', 'rpm') or a config object merged with defaults.

// Using a preset name
const rpm = new Gauge(el1, 'rpm');

// Using a custom config object
const custom = new Gauge(el2, {
  min: 0, max: 200,
  label: 'KPH', units: 'km/h',
  majorTicks: 11, minorTicks: 2
});

Methods

setValue(value, options?)

Set the gauge value. Animates by default with spring-damper physics. Pass { immediate: true } to snap instantly. Dispatches gauge:valuechange.

sweep()

Runs a self-test sweep animation: needle goes to max then returns. Dispatches gauge:sweepcomplete when done.

destroy()

Disconnects the resize observer, cancels animation, and removes the canvas element. Call this before removing the gauge from the DOM.

gauge.setValue(75);                   // animated
gauge.setValue(75, { immediate: true }); // instant snap
gauge.sweep();                        // self-test
gauge.destroy();                      // cleanup

Properties

value (getter/setter)

Get or set the current target value. Setting calls setValue() with animation.

vibration (setter)

Enable or disable needle vibration effect (subtle jitter, useful for RPM gauges).

gauge.value = 50;        // same as gauge.setValue(50)
console.log(gauge.value); // 50
gauge.vibration = true;   // enable needle jitter

Events

Events are dispatched on the container element passed to the constructor.

• gauge:ready — Fired after construction and initial render.
• gauge:valuechange — Fired on setValue(). Detail: { value }.
• gauge:sweepcomplete — Fired when a sweep() animation finishes.

Configuration Reference

All configuration keys with their types and defaults. Pass these in the config object to the constructor.

Here is a "kitchen sink" gauge demonstrating many config keys:

new Gauge(el, {
  min: 0, max: 120,
  label: 'POWER', units: 'kW',
  majorTicks: 7, minorTicks: 3,
  faceStyle: 'dark',
  showDigitalValue: true,
  labelFontSize: 1.2,
  zones: [
    { start: 80, end: 100, color: 'rgba(255,165,0,0.15)' },
    { start: 100, end: 120, color: 'rgba(204,32,32,0.15)' }
  ],
  texts: [{ text: 'EV', x: 0, y: -0.25 }]
});

Colors & Theming

The colors object overrides individual gauge colors. All keys are optional; unset keys use smart defaults based on faceStyle.

Three gauges: default light, custom colors, and dark face.

Modern Features

These advanced features enable contemporary instrument cluster designs with glowing needles, illuminated ticks, segmented rings, digital readouts, and embedded sub-gauges. See the modern preset for a full working example.

needleGlow

When true, adds a soft colored glow behind the needle using the needle's color. Simple boolean toggle.

digitalDisplay

Advanced digital readout replacing the simple showDigitalValue boolean. Provides full control over position, size, colors, and units display.

activeTicks

Illuminates tick marks from minimum up to the current needle position, creating a "fill" effect.

innerRing

Draws a decorative circular ring inside the gauge face, useful for framing a digital readout.

microTicks

Draws a dense set of fine tick marks for high-resolution scales (e.g. one per km/h on a speedometer).

progressArc

A colored arc that fills proportional to the current gauge value, drawn along the tick arc.

rings

External segmented ring indicators, often used for RPM/rev bands outside the main bezel. Each ring is an object in the array:

complications

Embedded sub-gauges on the dial face (fuel gauge, oil temp, etc.). Each complication is an object in the array:

onDraw

Custom draw callback invoked each animation frame after the needle is drawn. Receives the canvas 2D context and a state object with { value, angle, centerX, centerY, radius }.

Here is the built-in modern preset demonstrating these features together:

new Gauge(el, {
  min: 0, max: 320,
  units: 'km/h',
  faceStyle: 'dark',
  needleGlow: true,
  colors: { needle: '#FF8800', ticks: '#CCCCCC' },
  digitalDisplay: {
    show: true, fontSize: 2,
    color: '#FFFFFF',
    showUnits: true, unitsColor: '#999999'
  },
  activeTicks: { color: '#FFAA00' },
  innerRing: { radius: 0.38, color: '#333333', width: 2 },
  microTicks: { count: 320, color: '#444444' },
  rings: [{
    min: 0, max: 8000, width: 0.04, offset: 1.08,
    segments: 30,
    gradient: [
      { at: 0, color: '#2255FF' },
      { at: 1, color: '#FF2200' }
    ]
  }],
  complications: [{
    type: 'arc',
    startAngle: 216, endAngle: 144,
    arcOffset: 0.82, arcWidth: 0.012,
    fill: { color: '#00CCBB', glow: true },
    labels: [
      { text: 'E', position: 0 },
      { text: 'F', position: 1 }
    ]
  }]
});

Presets Reference

Built-in presets for common automotive gauges. Pass the preset name as the config argument.

Container Requirements

The container element must have explicit dimensions. The gauge uses the smaller of width/height to maintain a square aspect ratio. Use aspect-ratio: 1 for best results.

<!-- Recommended: square container -->
<div style="width: 200px; aspect-ratio: 1"></div>

<!-- Also works: explicit width + height -->
<div style="width: 300px; height: 300px"></div>

<!-- Responsive: percentage width -->
<div style="width: 50%; aspect-ratio: 1"></div>

Advanced

NeedlePhysics

The needle uses a second-order spring-damper system. The equation of motion:

// acceleration = stiffness * (target - angle) - damping * velocity
// Semi-implicit Euler integration at 120Hz fixed timestep

• stiffness — Higher values make the needle respond faster.
• damping — Higher values reduce oscillation/overshoot.

Constructor: new NeedlePhysics(config). Key methods: setTarget(angle, immediate), update(timestamp), isSettled(threshold).

GaugeRenderer

Handles all canvas drawing. Static layers (bezel, face, ticks, numbers) are pre-rendered to an OffscreenCanvas. Per-frame layers (needle, center cap, digital value) are drawn each animation frame.

Layer pipeline: Outer Shadow → Bezel → Inner Lip → Face → Texts → Zones → Ticks → Numbers → Label → Odometer → Glass Highlight.

Compare stiffness/damping: "loose" (stiffness 40, damping 8) vs "tight" (stiffness 300, damping 30).