npm package: @lucidian/react-dashboard-gauges
Description: Interactive gauge components for visualizing data in customizable dashboards built with React.
Latest version: 1.0.12

# 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

```bash
npm i @lucidian/react-dashboard-gauges
```

---

## Usage

Import and use the gauge components in your React app:

```tsx
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:**

```tsx
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:**

```tsx
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:**

```tsx
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:**

```tsx
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](https://recharts.org/).

**Import:**

```tsx
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:**

```tsx
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:**

```tsx
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

```tsx
// 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.

---