@sourcentis/chartjs-gauge

A Chart.js plugin that adds a gauge chart type — a half-doughnut with an animated needle and a configurable value label.

Features

• Gauge chart type (type: 'gauge') built on Chart.js's doughnut controller
• Animated needle with configurable radius, width, length, and color
• Value label with custom formatter, background, border-radius, padding, and color
• Supports minValue to offset the gauge starting point
• Compatible with Chart.js v4
• Works as a Laravel Composer package (publishes pre-built assets) or a standalone npm package

Installation

npm / yarn

npm install chart.js @sourcentis/chartjs-gauge
# or
yarn add chart.js @sourcentis/chartjs-gauge

Composer (Laravel)

composer require sourcentis/chartjs-gauge

Then publish the pre-built assets:

php artisan vendor:publish --tag=chartjs-gauge-assets

This copies the dist/ files to public/vendor/chartjs-gauge/.

Quick Start

ES module (Vite / webpack)

import { Chart } from "chart.js";
import "@sourcentis/chartjs-gauge"; // auto-registers the controller

const ctx = document.getElementById("myGauge");

new Chart(ctx, {
    type: "gauge",
    data: {
        datasets: [{
            value: 65,                                          // needle position
            data: [33, 66, 100],                               // segment boundaries
            backgroundColor: ["#E15759", "#F28E2B", "#59A14F"],
        }],
    },
    options: {
        needle: {
            radiusPercentage: 2,
            widthPercentage: 3.2,
            lengthPercentage: 80,
            color: "rgba(0, 0, 0, 1)",
        },
        valueLabel: {
            display: true,
            formatter: (value) => `${value}%`,
            color: "rgba(255, 255, 255, 1)",
            backgroundColor: "rgba(0, 0, 0, 0.8)",
        },
    },
});

CDN (UMD)

<script src="https://cdn.jsdelivr.net/npm/chart.js@4/dist/chart.umd.min.js"></script>
<script src="/vendor/chartjs-gauge/chartjs-gauge.min.js"></script>

<canvas id="myGauge"></canvas>
<script>
    new Chart(document.getElementById("myGauge"), {
        type: "gauge",
        data: {
            datasets: [{
                value: 65,
                data: [33, 66, 100],
                backgroundColor: ["#E15759", "#F28E2B", "#59A14F"],
            }],
        },
    });
</script>

Dataset Properties

| Property | Type | Default | Description | |------------|----------|---------|---------------------------------------------------------| | value | number | — | Required. Current needle position. | | minValue | number | 0 | Minimum gauge value (offset starting point). | | data | number[] | — | Required. Segment boundary values (cumulative). | | backgroundColor | string[] | — | Colors for each segment. |

Segments vs. value

data defines the segment boundaries on the gauge arc. The value property controls where the needle points independently of the segments.

// Three segments: 0–33 (red), 33–66 (orange), 66–100 (green)
// Needle at 50 (in the orange zone)
datasets: [{
    value: 50,
    data: [33, 66, 100],
    backgroundColor: ["#E15759", "#F28E2B", "#59A14F"],
}]

Using minValue

// Gauge from -20 to +20, needle at +5
datasets: [{
    value: 5,
    minValue: -20,
    data: [-10, 0, 10, 20],
    backgroundColor: ["#d32f2f", "#ef5350", "#66bb6a", "#2e7d32"],
}]

Options

Needle

Configure via options.needle:

| Option | Type | Default | Description | |----------------------|----------|------------------------|--------------------------------------------------------------| | radiusPercentage | number | 2 | Needle pivot circle radius as % of chart width. | | widthPercentage | number | 3.2 | Needle base width as % of chart width. | | lengthPercentage | number | 80 | Needle length as % of the arc depth (inner→outer radius). | | color | string | "rgba(0, 0, 0, 1)" | Needle and pivot circle fill color. |

options: {
    needle: {
        radiusPercentage: 2,
        widthPercentage: 3.2,
        lengthPercentage: 80,
        color: "rgba(0, 0, 0, 1)",
    },
}

Value Label

Configure via options.valueLabel:

| Option | Type | Default | Description | |-------------------------|------------|-----------------------------|------------------------------------------------------------| | display | boolean | true | Show or hide the label. | | formatter | function | (v) => String(v) | Format the displayed value. Receives the raw value. | | fontSize | number | 12 | Font size in pixels. | | color | string | "rgba(255, 255, 255, 1)" | Text color. | | backgroundColor | string | "rgba(0, 0, 0, 0.8)" | Background fill color. | | borderRadius | number | 5 | Background corner radius in pixels. | | padding | object | {top:5,right:10,bottom:5,left:10} | Inner padding around the label text. | | bottomMarginPercentage| number | 5 | Vertical offset from gauge center as % of chart width. |

options: {
    valueLabel: {
        display: true,
        formatter: (value) => `${value.toFixed(1)}%`,
        fontSize: 14,
        color: "#ffffff",
        backgroundColor: "rgba(0, 0, 0, 0.8)",
        borderRadius: 4,
        padding: { top: 6, right: 12, bottom: 6, left: 12 },
        bottomMarginPercentage: 5,
    },
}

Formatter examples

// Percentage
formatter: (value) => `${value}%`

// Currency
formatter: (value) => new Intl.NumberFormat("fr-FR", { style: "currency", currency: "EUR" }).format(value)

// Score label
formatter: (value) => value >= 80 ? "Excellent" : value >= 50 ? "Moyen" : "Faible"

// Hide label
valueLabel: { display: false }

Arc (inherited from Doughnut)

The gauge arc is a 180° half-doughnut by default. You can override these Chart.js options:

| Option | Default | Description | |-----------------|---------|----------------------------------| | rotation | -90 | Start angle in degrees. | | circumference | 180 | Arc span in degrees. | | cutout | "50%" | Inner radius as % of outer radius. |

Examples

Maturity score (0–100, three zones)

new Chart(ctx, {
    type: "gauge",
    data: {
        datasets: [{
            value: 72,
            data: [40, 80, 100],
            backgroundColor: ["#E15759", "#F28E2B", "#59A14F"],
        }],
    },
    options: {
        needle: { color: "#333" },
        valueLabel: {
            formatter: (v) => `${v} / 100`,
            backgroundColor: "#333",
        },
    },
});

Full-circle gauge (360°)

new Chart(ctx, {
    type: "gauge",
    data: {
        datasets: [{
            value: 270,
            data: [90, 180, 270, 360],
            backgroundColor: ["#4e79a7", "#f28e2b", "#e15759", "#76b7b2"],
        }],
    },
    options: {
        rotation: -180,
        circumference: 360,
        cutout: "70%",
        valueLabel: { formatter: (v) => `${v}°` },
    },
});

With Chart.js datalabels plugin

import ChartDataLabels from "chartjs-plugin-datalabels";
Chart.register(ChartDataLabels);

options: {
    plugins: {
        datalabels: {
            formatter: () => null,  // hide segment labels
        },
    },
}

Laravel / Vite Integration

If you use this package via Composer and build assets with Vite, add an alias in vite.config.mjs:

import path from "path";

export default defineConfig({
    resolve: {
        alias: {
            "@sourcentis/chartjs-gauge": path.resolve(
                __dirname,
                "vendor/sourcentis/chartjs-gauge/dist/chartjs-gauge.esm.js"
            ),
        },
    },
});

Then import normally in your JS:

import "@sourcentis/chartjs-gauge";

API

Named export

import { GaugeController } from "@sourcentis/chartjs-gauge";

// Manual registration (if you don't want auto-registration on import)
Chart.register(GaugeController, ArcElement);

Default export

import ChartjsGauge from "@sourcentis/chartjs-gauge";

ChartjsGauge.install(Chart); // same as Chart.register(GaugeController, ArcElement)

Browser Support

Same as Chart.js v4 — all modern browsers (Chrome, Firefox, Safari, Edge).

Contributing

1. Clone the repo
2. npm install
3. npm run dev — watch mode
4. npm run build — production build

License

MIT © Sourcentis

Acknowledgements

Inspired by chartjs-gauge by haiiaaa.