PHPackages                             kasperi/gaugeit-js - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Admin Panels](/categories/admin)
4. /
5. kasperi/gaugeit-js

ActiveLibrary[Admin Panels](/categories/admin)

kasperi/gaugeit-js
==================

Prebuilt browser assets for the dependency-free Gaugeit.js SVG gauge instrument library.

v0.1.1(today)01↑2900%MITJavaScriptPHP >=8.1CI passing

Since Jul 27Pushed todayCompare

[ Source](https://github.com/kasperikoski/Gaugeit.js)[ Packagist](https://packagist.org/packages/kasperi/gaugeit-js)[ Docs](https://github.com/kasperikoski/gaugeit.js)[ RSS](/packages/kasperi-gaugeit-js/feed)WikiDiscussions main Synced today

READMEChangelog (2)DependenciesVersions (3)Used By (0)

Gaugeit.js
==========

[](#gaugeitjs)

Gaugeit.js is a lightweight, dependency-free, extensible analog gauge library built with native SVG, JavaScript, and a small optional CSS file.

Gaugeit.js includes eight gauge types:

- `arc`: a clean semicircular gauge with configurable colored or transparent sectors;
- `classic`: a framed, white, old-style instrument meter;
- `classic-linear`: a cream-faced vintage instrument with a travelling linear indicator;
- `center-zero`: a cream heritage bidirectional dial whose resting reference is centered at zero;
- `classic-linear-zero`: the framed classic linear instrument with a fixed zero reference;
- `heritage-round`: a circular vintage instrument built from the shared classic layers;
- `line-scale`: a tick-focused gauge with independently configurable major and minor scale lines;
- `rolling-tape`: a heritage aircraft-style moving number tape behind a fixed edge-to-edge reference line.

The runtime has no image, jQuery, canvas, or framework dependency. It can be used from a classic `` tag, an ES module, a custom element, React, Twig, Blade, or another server-rendered application.

> **Current release:** `0.1.1`

Why SVG
-------

[](#why-svg)

SVG is used as the default renderer because it is resolution-independent, responsive without device-pixel-ratio bookkeeping, easy to theme with CSS, accessible through normal DOM attributes, and efficient for the relatively small number of vector elements used by analog gauges. Static parts are rendered once. During animation, Gaugeit.js normally updates only the active pointer, linear indicator, or rolling tape slots together with readout text and the ARIA value.

Browser installation with separate files
----------------------------------------

[](#browser-installation-with-separate-files)

This is the recommended browser installation. It keeps JavaScript and CSS separately cacheable.

```

  const gauge = Gaugeit.createGauge('#score-gauge', {
    type: 'arc',
    min: 0,
    max: 3000,
    value: 625,
    zones: [
      { min: 0, max: 500, color: '#ef4444' },
      { min: 500, max: 1000, color: '#facc15' },
      { min: 1000, max: 2100, color: '#22c55e' },
      { min: 2100, max: 2500, color: '#facc15' },
      { min: 2500, max: 3000, color: '#ef4444' }
    ]
  });

  gauge.setValue(1420);

```

Open `example.html` directly in a browser to see all eight built-in types, live controls, and a four-instrument customization gallery that replaces preset colors entirely through options.

One-file standalone browser installation
----------------------------------------

[](#one-file-standalone-browser-installation)

The standalone bundle exposes the same `window.Gaugeit` API and injects the complete responsive stylesheet automatically. The stable `#gaugeit-styles` marker ensures that the stylesheet is injected only once.

```

  Gaugeit.createGauge('#gauge', { type: 'classic', value: 72 });

```

The standalone and separate-file builds are generated from the same canonical `src/gaugeit.css` source. Neither contains a separately maintained CSS copy.

Native browser ES module
------------------------

[](#native-browser-es-module)

```

  import Gaugeit, { createGauge } from './dist/gaugeit.esm.js';

  const gauge = createGauge(document.querySelector('#temperature'), {
    type: 'classic',
    min: -20,
    max: 120,
    value: 68,
    readout: {
      title: { visible: true, text: 'COOLANT' },
      unit: { visible: true, text: '°C' }
    }
  });

  console.log(Gaugeit.VERSION);

```

npm installation
----------------

[](#npm-installation)

```
npm install gaugeit.js@0.1.1
```

```
import { createGauge } from 'gaugeit.js';
import 'gaugeit.js/css';

const gauge = createGauge('#gauge', { type: 'arc', value: 64 });
```

npm consumers receive prebuilt JavaScript, CSS, declarations, and source maps. Applications normally do not modify anything in `dist/`.

### CommonJS

[](#commonjs)

```
const { createGauge } = require('gaugeit.js');
const gauge = createGauge(document.querySelector('#gauge'), { value: 64 });
```

CDN installation
----------------

[](#cdn-installation)

Use exact versions in production. CDN consumers need no installation or compilation.

### jsDelivr, recommended two-file installation

[](#jsdelivr-recommended-two-file-installation)

```

```

### jsDelivr, one-file installation

[](#jsdelivr-one-file-installation)

```

```

### UNPKG

[](#unpkg)

```

```

The UNPKG one-file equivalent is `https://unpkg.com/gaugeit.js@0.1.1/dist/gaugeit.standalone.min.js`.

Built-in gauge gallery
----------------------

[](#built-in-gauge-gallery)

**Arc zones.** A clean semicircular gauge with configurable colored sectors, tapered zones, and true transparent gaps.

[![Arc zones gauge with configurable colored sectors](docs/assets/arc_zones.png)](docs/assets/arc_zones.png)

**Classic instrument.** A framed white instrument with a glass highlight, fine scale markings, and a traditional spear pointer.

[![Classic framed analog instrument](docs/assets/classic_instrument.png)](docs/assets/classic_instrument.png)

**Heritage round.** A circular vintage instrument built from the shared classic face, bezel, scale, and pointer layers.

[![Heritage round analog instrument](docs/assets/heritage_round.png)](docs/assets/heritage_round.png)

**Line scale.** A tick-focused gauge with independently configurable major divisions, minor ticks, labels, and pointer styling.

[![Line scale gauge](docs/assets/line_scale.png)](docs/assets/line_scale.png)

**Classic linear instrument.** A cream-faced vintage scale with configurable zones, fine ticks, and a travelling hairline indicator.

[![Classic linear analog instrument](docs/assets/classic_linear_instrument.png)](docs/assets/classic_linear_instrument.png)

**Center zero.** A signed bidirectional dial with a fixed center reference and pointer movement on both sides of zero.

[![Center-zero bidirectional analog gauge](docs/assets/center_zero.png)](docs/assets/center_zero.png)

**Classic linear center zero.** The classic linear instrument with a permanent zero marker and signed indicator travel in both directions.

[![Classic linear center-zero instrument](docs/assets/classic_linear_center_zero.png)](docs/assets/classic_linear_center_zero.png)

**Heritage rolling tape.** An aircraft-style numeric tape that moves behind a fixed edge-to-edge reference line.

[![Heritage aircraft-style rolling tape instrument](docs/assets/heritage_rolling_tape.png)](docs/assets/heritage_rolling_tape.png)

Customization example
---------------------

[](#customization-example)

**Rose balance.** The heritage center-zero instrument recolored entirely through ordinary Gaugeit.js configuration options.

[![Rose-themed customization of the center-zero gauge](docs/assets/rose_balance.png)](docs/assets/rose_balance.png)

Minimal configuration
---------------------

[](#minimal-configuration)

Only the target and value are required in ordinary use. Every gauge type supplies its own visual defaults.

```
const gauge = Gaugeit.createGauge('#gauge', {
  type: 'line-scale',
  value: 72
});
```

True transparent zones
----------------------

[](#true-transparent-zones)

A zone with `color: 'transparent'`, `color: 'none'`, or no color creates a real gap. The base track is not drawn under that interval unless `track.showUnderZones` is explicitly enabled.

```
zones: [
  { min: 0, max: 25, color: '#ef4444' },
  { min: 25, max: 40, color: 'transparent' },
  { min: 40, max: 80, color: '#22c55e' },
  { min: 80, max: 100, color: '#facc15' }
]
```

For compatibility with Gauge.js-style configuration, `strokeStyle` is accepted as an alias for a zone's `color`.

Radial zones may also taper smoothly. `width` remains the uniform fallback, while `taper.startWidth` and `taper.endWidth` define the thickness at the zone's numeric `min` and `max` endpoints. The direction therefore follows the value mapping even when `invert` is enabled:

```
zones: [
  {
    min: 0,
    max: 60,
    color: '#06b6d4',
    width: 18,
    taper: {
      startWidth: 0,
      endWidth: 36,
      segments: 56
    }
  }
]
```

`segments` controls curve smoothness and is clamped between 2 and 256. Tapered zones are rendered as filled SVG annular segments because a native SVG stroke cannot change width along one path. Uniform zones continue to use the lighter stroke representation.

Inverted scales
---------------

[](#inverted-scales)

Set the top-level `invert` option to `true` to mirror the value direction while keeping the configured geometry unchanged. The minimum and maximum swap visual endpoints, and ticks, labels, zones, and the pointer all follow the same value-based mapping:

```
createGauge('#fuel', {
  type: 'heritage-round',
  min: 0,
  max: 100,
  invert: true
});
```

`invert` defaults to `false`. Zones remain defined with their normal numeric `min` and `max` values; low-value warning zones therefore move automatically with the inverted scale and do not need to be rewritten.

Major and minor ticks
---------------------

[](#major-and-minor-ticks)

```
scale: {
  radius: 124,
  position: 'inside', // inside, outside, or cross
  major: {
    interval: 20,     // explicit value interval
    divisions: 5,     // used only when interval is null
    length: 24,
    width: 2.5,
    color: '#111827'
  },
  minor: {
    subdivisions: 4, // four minor lines between major ticks
    length: 11,
    width: 1,
    color: '#64748b'
  }
}
```

Pointer types
-------------

[](#pointer-types)

Built-in pointer shapes are:

- `needle`: traditional tapered needle;
- `line`: rounded line pointer;
- `arrow`: arrow-shaped pointer;
- `spear`: vintage instrument pointer.

```
pointer: {
  type: 'spear',
  length: 98,
  shaftLength: 67, // optional; null preserves the type-specific shape
  tailLength: 14,
  width: 9,
  color: '#111827',
  colorByZone: false,
  cap: {
    visible: true,
    stackOrder: 'above', // above or below the pointer shape
    radius: 9,
    color: '#20242a',
    strokeColor: '#ffffff',
    strokeWidth: 2
  }
}
```

Built-in gauge types paint their pointer or linear indicator after the readout, so it always crosses above title, value, and unit text. Caps default to `stackOrder: 'above'`. A custom type can use `'below'` when its pointer should cross over the center cap. This uses deterministic SVG paint order rather than CSS `z-index`.

Classic linear instrument
-------------------------

[](#classic-linear-instrument)

`classic-linear` reuses the classic cream panel, bezel, glass, readouts, scale configuration, zones, animation, jitter, and accessibility lifecycle. Its value moves a straight indicator instead of rotating a pointer:

```
createGauge('#signal', {
  type: 'classic-linear',
  min: 0,
  max: 100,
  value: 62,
  linear: {
    originY: 142,
    startX: 38,
    startY: 0,
    endX: 282,
    endY: 0,
    tickSide: 'negative',
    labelOffset: 38,
    zoneOffset: -16
  },
  indicator: {
    type: 'hairline', // hairline | marker | carriage
    position: 'cross',
    length: 84,
    centerOffset: 0, // positive moves upward on a horizontal axis
    width: 2.4,
    cap: { visible: false }
  },
  zones: [
    { min: 0, max: 20, color: '#b91c1c' },
    { min: 20, max: 70, color: 'transparent' },
    { min: 70, max: 100, color: '#15803d' }
  ]
});
```

The axis is defined by two points, so custom types may use horizontal, vertical, or diagonal linear scales. Linear Y coordinates use a Cartesian convention around `linear.originY`: `0` is the preset baseline, positive values move upward, and negative values move downward. X coordinates continue to increase to the right. The built-in classic-linear fallback therefore uses `startY: 0`, `endY: 0`, and title `y: 60`. `labelOffset`, `zoneOffset`, and `indicator.centerOffset` use the same positive-up convention for a left-to-right horizontal scale. `invert: true` reverses value direction without changing axis or zone definitions. Major and minor tick lengths remain independently configurable through `scale.major.length` and `scale.minor.length`.

Center-zero and rolling-tape gauges
-----------------------------------

[](#center-zero-and-rolling-tape-gauges)

The specialized built-ins use the same lifecycle, animation, jitter, zones, accessibility, responsive layout, and runtime update API as the other instruments.

The cream-faced radial `center-zero` preset keeps an automatically symmetric range around a custom reference value. Its title is an ordinary readout part and defaults between the pointer hub and the lower numeric value; `readout.title.x` and `readout.title.y` can move it anywhere in the dial:

```
createGauge('#trim', {
  type: 'center-zero',
  min: -50,
  max: 50,
  value: 12,
  centerZero: {
    zeroValue: 0,
    symmetric: true,
    marker: { color: '#5b4636', length: 26, width: 3 }
  }
});
```

For a straight scale, `classic-linear-zero` reuses the complete classic linear face, axis, ticks, labels, zones, indicator, clipping, and sizing system. It adds only a fixed zero-reference layer:

```
createGauge('#deviation', {
  type: 'classic-linear-zero',
  min: -100,
  max: 100,
  value: -28,
  geometry: { width: 520, height: 220 },
  centerZero: {
    zeroValue: 0,
    symmetric: true,
    marker: { visible: true, length: 34, centerOffset: 0 }
  }
});
```

`rolling-tape` keeps an edge-to-edge reference line fixed while the numerical scale moves smoothly underneath it. Its cream face is only a preset: every face, window, strip, tick, label, fade, reference-line, and zone color remains configurable.

```
createGauge('#altitude', {
  type: 'rolling-tape',
  geometry: { width: 300, height: 480 },
  min: 0,
  max: 10000,
  value: 4250,
  tape: {
    interval: 2000,
    minorSubdivisions: 3,
    majorSpacing: 58,
    stripColor: '#fff9ea',
    textColor: '#211f1a',
    indicatorColor: '#991b1b',
    windowInnerStrokeColor: '#d8cfbd'
  },
  readout: {
    title: { visible: true, text: 'ALTITUDE' },
    value: { visible: true, x: 150, y: 390 },
    unit: { visible: true, text: 'FT' }
  }
});
```

The optional separate tape value uses the same independently configurable `x` and `y`coordinates as every other readout part. It may be hidden when the moving tape itself is the only numeric display required.

All three presets accept normal `updateOptions()` calls, `invert`, custom formatters, custom CSS classes, and per-zone colors. Omitting an option always falls back to the type preset.

Warning lights and annunciators
-------------------------------

[](#warning-lights-and-annunciators)

Every built-in gauge type can host the shared optional `light` layer. The lamp is SVG, so its coordinates and radius scale with the gauge viewBox, it respects framed face clipping, and it remains correctly positioned at every rendered size. The component is disabled by default.

```
createGauge('#fuel', {
  type: 'heritage-round',
  min: 0,
  max: 100,
  value: 12,
  light: {
    visible: true,
    x: 93,
    y: 110,
    radius: 8,
    glowRadius: 20,
    glowSharpness: 0,
    glowOpacity: 0.15,
    color: 'red',
    offColor: '#f3ead6',
    pulse: false,
    blink: false,
    blinkInterval: 1000,
    flicker: true,
    flickerIntensity: 0.1,
    flickerGlowRadius: 0.1,
    flickerMinInterval: 45,
    flickerMaxInterval: 140,
    trigger: { mode: 'below', source: 'target', value: 15 }
  }
});
```

Built-in palettes are `red`, `green`, `blue`, `amber`, `yellow`, `orange`, `white`, `halogen`, `cyan`, and `brown`. Use `customColor` for an application-specific active color. The unlit lamp deliberately uses a softly diffused cream lens rather than a black bulb; `offColor`, `offEdgeColor`, `bezelColor`, and `bezelHighlightColor` can customize that hardware appearance. `radius` controls the physical lamp while `glowRadius` controls the halo independently and defaults to `20`. Set it to `null` to derive the halo radius from `radius * 1.82`. `glowSharpness` controls the halo blur: `0` uses a soft Gaussian glow, while `1` removes blur for a completely sharp edge. Intermediate values reduce the blur continuously. `glowOpacity` controls only the halo and defaults to `0.15`, independently from the illuminated lens `opacity`. The halo is painted below the opaque lamp hardware, so it becomes visible beyond the lamp edges instead of covering the lens. `pulse` adds a deliberately subtle steady-light breathing effect. `blink` alternates the complete illuminated and unlit lens states, so the dark half-cycle looks exactly like the normal switched-off lamp rather than a faded transparent bulb. Blink takes precedence if both blink and pulse are enabled. `flicker` adds rapid random changes to the amount of emitted light. `flickerIntensity`sets the maximum random loss from full light: `0` is steady and `1` may momentarily reach the real unlit-lens appearance. It never darkens the lit lens toward black. `flickerGlowRadius` independently varies the halo radius by a relative plus/minus amount: with `glowRadius: 20`, the default `0.1` produces radii between 18 and 22. Each change waits a random duration between `flickerMinInterval` and `flickerMaxInterval`. Flicker is independent and may be combined with either pulse or blink. Flicker is enabled by default, but has no visual effect while the lamp is hidden or inactive. Trigger modes are `manual`, `below`, `above`, and `between`. The trigger source defaults to `target`, so a low-value lamp does not flash merely because a startup animation begins at the minimum. Use `displayed` to follow the animated readout value or `pointer` to include visual jitter. For linear gauges, `light.y` follows the same positive-up coordinate convention as the linear axis.

`opacity` controls only the illuminated lens layered over an always-opaque unlit lens. The physical lamp and bezel therefore remain fully visible even at `opacity: 0`; `glowOpacity` remains the separate control for the halo.

Custom types can opt in with `Gaugeit.layers.light`; all built-in types already include the layer and use the same shared light defaults. The lamp remains disabled until `light.visible` is true. The interactive `example.html` explicitly enables blink and disables flicker for its heritage-round demonstration.

Intrinsic dimensions and host sizing
------------------------------------

[](#intrinsic-dimensions-and-host-sizing)

`classic-linear`, `classic-linear-zero`, and `rolling-tape` can change their internal instrument proportions through `geometry.width` and `geometry.height`. The type's configuration hook scales only fallback geometry; any explicitly supplied coordinate remains authoritative. `geometry.aspectRatio` may derive the missing dimension:

```
createGauge('#wide-signal', {
  type: 'classic-linear',
  geometry: { width: 560, aspectRatio: 2.8 }
});
```

These logical dimensions control composition and the SVG viewBox. Page layout can still size any gauge host independently with normal CSS. Gaugeit provides optional custom properties for common integrations:

```
#wide-signal {
  --gaugeit-width: 100%;
  --gaugeit-height: 220px;
  --gaugeit-aspect-ratio: 14 / 5;
}
```

Use `layout.mode: 'contain'` when both host width and height are constrained and the whole instrument must scale inside that box. Leave the default `intrinsic` mode when the SVG's natural aspect ratio should determine document height.

Optional readout text
---------------------

[](#optional-readout-text)

The title, numeric value, and unit are independent SVG text elements. The numeric value and unit are hidden by default so a gauge starts as a pure analog instrument. `x: 'auto'` centers a part in its instrument reference box. `y: 'auto'` uses `position: 'top'`, `center`, or `bottom`, with optional `margin`, `offsetX`, and `offsetY`. Offsets refine automatic placement only. Numeric coordinates are final SVG positions for radial gauges. In linear gauges, numeric Y coordinates are relative to `linear.originY` and increase upward, while numeric X coordinates increase rightward:

```
readout: {
  visible: true,
  title: { visible: true, text: 'PRESSURE', x: 160, y: 24 },
  value: { visible: true, x: 160, y: 50, fractionDigits: 0 },
  unit: { visible: true, text: 'kPa', x: 160, y: 72 }
}
```

For the built-in `arc` type, the title defaults to `x: 'auto', y: 35`. An enabled numeric value defaults to `x: 160, y: 130`, inside the arc between the upper scale labels and the pointer pivot.

Custom arc sweep and responsive layout
--------------------------------------

[](#custom-arc-sweep-and-responsive-layout)

`geometry.startAngle` and `geometry.endAngle` define the pointer and scale sweep. For example, a centered 240-degree arc uses `startAngle: 150` and `endAngle: 390`. Interactive controls can use `Gaugeit.geometry.centeredArcAngles(sweep, centerAngle)`: a center angle of `0` means the normal upright orientation (internally SVG angle 270), while positive values rotate clockwise. The difference may be configured up to 360 degrees. Full circles are rendered as two SVG half-arcs, and the maximum tick/label endpoint is deduplicated by default so it does not overlap the minimum endpoint.

The default `layout.mode: 'intrinsic'` computes a content-aware viewBox. Increasing a sweep to 360 degrees therefore increases the gauge's natural height and pushes the following document content down instead of overflowing it. Use `layout.mode: 'contain'`when the host has an explicit CSS width and height and the complete instrument should scale down to fit that box:

```
layout: {
  mode: 'contain', // intrinsic | contain
  padding: 10
}
```

Classic panel faces use `face.fit: 'content'`, so the face expands when a larger sweep or moved readout needs more drawing space. `face.minWidth` and `face.minHeight` define optional lower limits for a content-fitted frame. The built-in framed instruments also use `face.clipContent: true`, which clips pointers, indicators, zones, ticks, labels, and readouts to the inner bezel instead of allowing them to overflow the frame. Circular faces remain available through `shape: 'circle'` and the ready-made `heritage-round` type.

Startup animation
-----------------

[](#startup-animation)

```
animation: {
  enabled: true,
  duration: 900,
  easing: 'easeOutCubic',
  animateOnInit: true,
  startFrom: 'min', // min, max, value, or a number
  respectReducedMotion: true
}
```

Set `startFrom: 'value'` or `animateOnInit: false` when the pointer must already be at its final position on first paint.

Realistic pointer jitter
------------------------

[](#realistic-pointer-jitter)

Jitter is a pointer-like visual effect. It randomizes the radial pointer angle or linear indicator position without changing the readout, `getValue()`, `getDisplayedValue()`, accessibility value, or application data.

```
effects: {
  jitter: {
    enabled: true,
    amplitude: 0.8,
    amplitudeUnit: 'value', // value or percent
    frequency: 5,
    smoothing: 0.88,
    whenIdleOnly: true
  }
}
```

Animation and jitter automatically pause when the page is hidden. They also pause when the gauge is offscreen when `IntersectionObserver` is available.

Updating an instance
--------------------

[](#updating-an-instance)

```
gauge.setValue(76);
gauge.setValue(18, { duration: 1400, easing: 'easeInOutCubic' });
gauge.setValue(50, { animate: false });

gauge.updateOptions({
  pointer: { type: 'line', color: '#dc2626' },
  labels: { fractionDigits: 1 }
});

// Replace the complete instance configuration and discard earlier overrides.
gauge.replaceOptions({ type: 'classic', min: 0, max: 100 });

gauge.pause();
gauge.resume();
gauge.refresh();
gauge.destroy();
```

`set(value)` and `setOptions(options)` are convenience aliases. `updateOptions()`merges a partial patch, while `replaceOptions()` replaces the complete user-option object and is useful for declarative framework adapters.

Data-attribute initialization
-----------------------------

[](#data-attribute-initialization)

```

  Gaugeit.autoMount();

```

Auto mounting is duplicate-safe.

Custom element
--------------

[](#custom-element)

```

Gaugeit.defineGaugeitElement();

```

The `value` property or attribute can be changed later.

With npm, the same API is available through the explicit Web Component subpath:

```
import { defineGaugeitElement } from 'gaugeit.js/web-component';
import 'gaugeit.js/css';

defineGaugeitElement();
```

React
-----

[](#react)

```
import { useState } from 'react';
import Gaugeit from 'gaugeit.js/react';
import 'gaugeit.js/css';

export default function DashboardGauge() {
  const [value, setValue] = useState(62);

  return (

  );
}
```

The React adapter is intentionally thin. React owns the host node and Gaugeit.js owns only the generated content inside it. The published `gaugeit.js/react` entry is normal browser-ready ESM JavaScript and does not require a package consumer to transpile JSX inside `node_modules`. It replaces the complete `options` prop when that prop changes, keeps an explicit `value` prop authoritative, destroys the instance on unmount, and forwards a ref to the live `Gauge` instance.

Laravel, Twig, or plain PHP
---------------------------

[](#laravel-twig-or-plain-php)

Copy the prebuilt files into a public vendor directory, include the CSS and UMD bundle, and initialize from the page module. No PHP integration is required.

A Blade example is included in `examples/laravel-blade.blade.php`.

### Composer distribution

[](#composer-distribution)

The package includes Composer metadata and a cross-platform vendor binary.

```
composer require kasperi/gaugeit-js:^0.1
vendor/bin/gaugeit-install-assets public/assets/vendor/gaugeit
```

The default command copies the recommended `gaugeit.umd.min.js` and `gaugeit.min.css`. Use `--standalone` for the one-file build, `--all` for all browser assets, or `--clean` to remove only known old Gaugeit.js assets before copying. Unrelated destination files are never removed.

Composer consumers receive prebuilt assets and do not need Node.js, npm, esbuild, or a frontend compilation step. A consuming project can automate the explicit asset command in its own `composer.json`:

```
{
  "scripts": {
    "assets:gaugeit": "vendor/bin/gaugeit-install-assets public/assets/vendor/gaugeit",
    "post-install-cmd": [
      "@assets:gaugeit"
    ],
    "post-update-cmd": [
      "@assets:gaugeit"
    ]
  }
}
```

The dependency itself deliberately does not write into an application's public directory during Composer installation.

For server-rendered applications, install the assets into a versioned public vendor path, load them through the application's asset helper, and initialize gauges from a reusable module or duplicate-safe data-attribute initializer.

Extending gauge types
---------------------

[](#extending-gauge-types)

A type is a name, a defaults object, and an ordered array of layers. A layer renders static SVG and may return a small controller whose `update(value, state)` method is called for dynamic changes.

```
Gaugeit.registerGaugeType('football-score', {
  description: 'A compact score-performance meter.',
  defaults: {
    geometry: { startAngle: 200, endAngle: 340 },
    pointer: { type: 'arrow', color: '#0f172a' },
    readout: { title: { visible: true, text: 'FORM' } }
  },
  layers: [
    Gaugeit.layers.face,
    Gaugeit.layers.zones,
    Gaugeit.layers.ticks,
    Gaugeit.layers.labels,
    Gaugeit.layers.pointer,
    Gaugeit.layers.readout
  ]
});
```

Custom layers can add SVG decorations, markers, secondary pointers, trend arrows, warning lights, or a completely different visual language without changing the animation core.

See `docs/creating-gauge-types.md` for a complete custom layer example.

Accessibility
-------------

[](#accessibility)

The generated root uses `role="meter"` and receives `aria-valuemin`, `aria-valuemax`, and `aria-valuenow`. Provide a meaningful label and optional value text:

```
accessibility: {
  label: 'Prediction accuracy',
  description: 'Accuracy across the last 50 predictions.',
  valueText: (value) => `${Math.round(value)} percent accurate`
}
```

Color should not be the only way to communicate meaning. Keep labels, text, or surrounding explanations available for important status information.

Browser support
---------------

[](#browser-support)

Gaugeit.js targets current evergreen browsers with native SVG, ES2018+, `requestAnimationFrame`, and modern DOM APIs. The UMD build works as a classic script. The ESM build works in modern module-aware browsers and bundlers.

Optional optimizations degrade safely:

- no `IntersectionObserver`: the gauge continues running while offscreen;
- no `matchMedia`: reduced-motion detection is skipped;
- no `customElements`: only the optional web-component adapter is unavailable.

Build and tests
---------------

[](#build-and-tests)

Maintainers edit files in `src/`, adapters, tests, documentation, and build scripts. Install the locked development toolchain and regenerate every distribution format:

```
npm ci
npm run clean
npm run build
npm run dev
npm run typecheck
npm test
npm run test:browser
npm run check
npm pack --dry-run
npm publish --dry-run
```

`npm run build` uses esbuild to recreate the complete `dist/` directory, including normal and minified ESM, UMD, CommonJS, standalone bundles, source maps, CSS, declarations, and the manifest. `npm run dev` watches source files. `npm run check`starts from a clean directory and runs the build, declaration validation, automated tests, DOM smoke test, npm package-content dry run, and Composer validation when Composer is available. `prepublishOnly` runs the same full check.

Minified files, source maps, embedded standalone CSS, declarations in `dist/`, and other generated files must never be edited manually. Change their canonical sources and run `npm run build`.

The optional `npm run test:chromium` command starts a temporary local HTTP server and uses a globally available Chromium executable. It is intentionally separate from the portable default checks.

Distribution policy
-------------------

[](#distribution-policy)

`dist/` is intentionally committed. GitHub source downloads, Composer installations, and CDN/npm consumers receive ready-to-use browser files without requiring Node.js. CI runs a clean build and can detect differences in the committed output. Package users receive prebuilt assets; only maintainers run the distribution build.

Package layout
--------------

[](#package-layout)

```
Gaugeit.js/
├── src/                  Canonical modular source and CSS
├── dist/                 Reproducible, committed distribution files
├── adapters/react/       Optional React adapter and declarations
├── docs/                 Architecture, API, and development documentation
├── examples/             Framework and custom-type examples
├── tests/                Unit, DOM, packaging, and installer tests
├── scripts/              Build and local validation scripts
├── bin/                  Composer asset installer
└── example.html          Interactive standalone demonstration

```

Release metadata
----------------

[](#release-metadata)

Version: `0.1.1`. npm package: `gaugeit.js`. Composer package: `kasperi/gaugeit-js`. Repository: `https://github.com/kasperikoski/gaugeit.js`.

Build and CI workflows validate release artifacts. Publishing to GitHub, npm, and Packagist is a manual maintainer action.

Contributing and security
-------------------------

[](#contributing-and-security)

Contribution setup and pull-request requirements are documented in `CONTRIBUTING.md`. Report suspected vulnerabilities privately as described in `SECURITY.md`; do not disclose them in public issues.

License
-------

[](#license)

MIT License. See `LICENSE`.

###  Health Score

36

—

LowBetter than 79% of packages

Maintenance100

Actively maintained with recent releases

Popularity2

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity33

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~0 days

Total

2

Last Release

0d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/55558433?v=4)[kasperikoski](/maintainers/kasperikoski)[@kasperikoski](https://github.com/kasperikoski)

---

Top Contributors

[![kasperikoski](https://avatars.githubusercontent.com/u/55558433?v=4)](https://github.com/kasperikoski "kasperikoski (2 commits)")

---

Tags

javascriptsvgdashboardgaugefrontend-assets

### Embed Badge

![Health badge](/badges/kasperi-gaugeit-js/health.svg)

```
[![Health](https://phpackages.com/badges/kasperi-gaugeit-js/health.svg)](https://phpackages.com/packages/kasperi-gaugeit-js)
```

###  Alternatives

[digital-creative/nova-dashboard

The missing dashboard for nova.

7171.8k1](/packages/digital-creative-nova-dashboard)[eliseekn/laravel-metrics

Generate easily metrics and trends data of your models for your dashboards.

1347.7k](/packages/eliseekn-laravel-metrics)[jubeki/nova-card-linkable

A Linkeable Card for the Laravel Nova Dashboard.

19277.1k](/packages/jubeki-nova-card-linkable)[plastyk/dashboard

An extendable dashboard for Silverstripe

2045.0k2](/packages/plastyk-dashboard)[putyourlightson/craft-dashboard-begone

Removes the dashboard and redirects users to entries.

1180.7k1](/packages/putyourlightson-craft-dashboard-begone)[superv/platform

SuperV Platform Package

2412.4k5](/packages/superv-platform)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)