React Dashboard Gauges

Interactive gauge components for visualizing data in customizable dashboards built with React.

Features

• Multiple gauge types (circular, linear, etc.)
• Responsive design
• Easy integration with APIs
• Customizable appearance and thresholds

Getting Started

1. Run the development server

npm i @lucidian/react-dashboard-gauges

Usage

Import and use the gauge components in your React app:

import { ArcGauge } from '@lucidian/react-dashboard-gauges';

<ArcGauge value={75} label="CPU Usage" />

Gauge Types & Props

ArcGauge

A semi-circular gauge for showing a value as a percentage (0–100).

Import:

import { ArcGauge } from '@lucidian/react-dashboard-gauges';

| Prop | Type | Default | Description | |------------------|-------------------------------------|--------------|-------------------------------------------------| | value | number | required | Value to display (0–100) | | size | number | 200 | Gauge diameter (px) | | thickness | number | 48 | Arc thickness (px) | | scale | number | 1.0 | Overall scale factor | | color | string | #42a5f5 | Filled arc color | | backgroundColor | string | #e0e0e0 | Unfilled arc color | | label | string or (val: number) => node | — | Custom label or label render function | | duration | number | 1 | Animation duration (seconds) | | demoMode | boolean | false | Show random demo values |

TempArcGauge

A temperature-focused semi-circular gauge supporting thresholds, colored sections, and multiple units.

Import:

import { TempArcGauge } from '@lucidian/react-dashboard-gauges';

| Prop | Type | Default | Description | |------------------|-------------------------------------|----------------------------|---------------------------------------------------------| | value | number | required | Temperature value (in Celsius by default) | | size | number | 200 | Gauge diameter (px) | | thickness | number | 48 | Arc thickness (px) | | scale | number | 1.0 | Overall scale factor | | colors | [string, string, string] | See below | Section colors (e.g. ["#2e7d32","#fbc02d","#c62828"]) | | start | number | 0 | Minimum temperature | | end | number | 130 | Maximum temperature | | thresholds | [number, number] | [80, 100] | Values at which color/sections change | | unit | "C", "F", or "K" | "C" | Temperature unit (Celsius, Fahrenheit, Kelvin) | | backgroundColor | string | #e0e0e0 | Background arc color | | label | string or (val: number) => node | — | Custom label or label render function | | duration | number | 1 | Animation duration (seconds) | | demoMode | boolean | false | Show random demo values |

Default colors: Green for low, yellow for warning, red for high. Section logic is based on thresholds.

BarGauge

A horizontal bar gauge with a threshold indicator (target), colored fill, and animated transitions.

Import:

import { BarGauge } from '@lucidian/react-dashboard-gauges';

| Prop | Type | Default | Description | |--------------|----------------|--------------|-------------------------------------------| | value | number | required | Value to display | | target | number | required | Target/threshold value | | total | number | 100 | Maximum possible value | | width | number | 200 | Width in px | | height | number | 48 | Height in px | | fillColor | string | #2e7d32 | Color up to target | | overColor | string | #c62828 | Color above target | | bgColor | string | #e0e0e0 | Bar background color | | scale | number | 1.0 | Overall scale factor | | duration | number | 1 | Animation duration (seconds) | | demoMode | boolean | false | Show random demo values |

ColumnGauge

A vertical column (bar) gauge with threshold/target and colored fill.

Import:

import { ColumnGauge } from '@lucidian/react-dashboard-gauges';

| Prop | Type | Default | Description | |--------------|----------------|--------------|----------------------------------------------| | value | number | required | Value to display | | units | string | "" | Unit label (shown at top of column) | | target | number | required | Target/threshold value | | total | number | 100 | Maximum possible value | | width | number | 68 | Width in px | | height | number | 200 | Height in px | | fillColor | string | #2e7d32 | Color up to target | | overColor | string | #c62828 | Color above target | | bgColor | string | #e0e0e0 | Column background color | | scale | number | 1.0 | Overall scale factor | | duration | number | 1 | Animation duration (seconds) | | demoMode | boolean | false | Show random demo values |

LineChartWidget

A time-series line chart built using Recharts.

Import:

import { LineChartWidget } from '@lucidian/react-dashboard-gauges';

| Prop | Type | Default | Description | |--------------|--------------|-------------|------------------------------------------------| | data | object[] | required| Chart data array | | xKey | string | required| Key for X axis | | yKey | string | required| Key for Y axis | | xAxisLabel | string | "" | X axis label | | yAxisLabel | string | "" | Y axis label | | lineColor | string | #ff9800 | Line color | | height | number | 300 | Chart height (px) | | width | number | 300 | Chart width (px) | | demoMode | boolean | false | Auto-generate random demo data | | windowSize | number | 10 | Number of points to show in demo mode |

Speedometer

A curved, classic speedometer gauge with animated needle.

Import:

import { Speedometer } from '@lucidian/react-dashboard-gauges';

| Prop | Type | Default | Description | |-------------|--------------|--------------|---------------------------------------| | value | number | required | Value to display | | min | number | 0 | Minimum value | | max | number | 10 | Maximum value | | width | number | 220 | SVG width (px) | | height | number | 190 | SVG height (px) | | tickCount | number | 11 | Number of tick marks | | labelStep | number | 1 | Interval between labels | | scale | number | 1.0 | Scale factor | | gaugeText | string | — | Optional label (shown inside gauge) | | demoMode | boolean | false | Show random demo values |

TorusGauge

A circular (donut) gauge with thresholds and band coloring.

Import:

import { TorusGauge } from '@lucidian/react-dashboard-gauges';

| Prop | Type | Default | Description | |------------------|-------------------------------------|--------------|---------------------------------------------| | value | number | required | Value as percentage (0–100) | | lowerThreshold | number | 30 | First threshold for color change | | upperThreshold | number | 70 | Second threshold for color change | | colors | string[] | See below | Band colors: [good, warning, danger] | | backgroundColor | string | #e5e7eb | Gauge background color | | size | number | 140 | Diameter in px | | thickness | number | 18 | Stroke width in px | | scale | number | 1.0 | Scale factor | | label | string or (val: number) => node | — | Custom center label or render function | | duration | number | 1.1 | Animation duration (seconds) | | demoMode | boolean | false | Show random demo values |

Default colors: green, yellow, red, mapped according to value and thresholds.

Example Usage

// ArcGauge Example
<ArcGauge value={75} label="CPU Usage" />

// TempArcGauge Example
<TempArcGauge value={95} thresholds={[80, 100]} unit="C" />

// BarGauge Example
<BarGauge value={65} target={70} />

// ColumnGauge Example
<ColumnGauge value={40} target={75} units="%" />

// LineChartWidget Example
<LineChartWidget data={yourData} xKey="time" yKey="load" />

// Speedometer Example
<Speedometer value={5.7} max={10} />

// TorusGauge Example
<TorusGauge value={45} lowerThreshold={30} upperThreshold={70} />

Notes

• All gauges support a demoMode prop, which, if set to true, animates the gauge with random values (helpful for dashboards with no live data).
• For customization, most gauges accept color, size, and label props, as well as animation duration and scaling.
• You can extend any gauge by wrapping the component.

License

This project is licensed under the MIT License.