Skip to content

DarkvoiceGit/gaugeChart

BranchesTags

Repository files navigation

GaugeChart

A highly customizable gauge chart component for React applications, built with D3.js.

Demo & Packager

Desc Url
You can see a live demo of the GaugeChart component at https://DarkvoiceGit.github.io/gaugeChart
NPM https://www.npmjs.com/package/@darkvoice/gauge-chart

Features

  • Customizable gauge with primary and secondary values
  • Configurable thresholds with color indicators
  • Interactive tooltips with customizable labels
  • Multiple gradient and fill style options
  • Extensive styling options for pointers, arcs, and tiles
  • Unit formatting and custom formatters

Installation

You can install the GaugeChart component from npm:

npm i @darkvoice/gauge-chart

Requirements

The component has the following peer dependencies:

  • React 16.8+ (Hooks support)
  • React DOM 16.8+

And the following dependencies:

  • D3.js 7.9+

These dependencies will be automatically installed or used from your project.

Basic Usage

import { GaugeChart } from '@darkvoicegit/gauge-chart';

function MyComponent() {
  return (
    <GaugeChart
      primary={40}
      secondary={30}
      options={{
        thresholdYellow: 60,
        thresholdRed: 80,
        enableToolTip: true
      }}
      tileArc={{
        tiles: 10,
        colorTileThresholdDefault: '#00ff00',
        colorTileThresholdYellow: '#ffff00',
        colorTileThresholdRed: '#ff0c4d'
      }}
    />
  );
}

Props

The GaugeChart component accepts the following props:

Prop Type Default Description
size 'default' | 'xxs' | 'xs' | 's' | 'sm' | 'm' | 'l' | 'xl' | 'xxl' | 'xxxl' 'default' Size preset: SVG width/height are set in pixels from the preset so the gauge and tick labels scale together (e.g. xxs = small, xxxl = large). Wrap in a container with max-width: 100% if you need it to shrink on small screens.
primary number - Primary value to display (required)
secondary number - Secondary value to display (optional)
unitTickFormatter function - Formatter function for unit tick labels
unit function - Formatter function for unit display
options object - General gauge configuration
options.thresholdYellow number - Threshold value for yellow warning level
options.thresholdRed number - Threshold value for red warning level
options.withOpacitySwitch boolean true Whether to enable opacity changes on hover
options.enableToolTip boolean true Whether to show tooltips
options.enableUnitTicks boolean true Whether to show unit ticks
options.tickFontsize string '1rem' Font size for tick labels
options.tickLabelColor string '#ffffff' Color for tick labels
options.tickRadiusScale number 1.12 Scale factor for tick radius
options.tickColor string '#777777' Color for ticks
options.circleScale number 0.5 Scale factor for center circle
options.enableInnerArc boolean true Whether to show inner arcs
options.fontColor string '#ffffff' Font color for labels and tooltips
options.tooltipBgColor object - Background color for tooltips
options.tooltipBgColor.r number - Red component (0-255)
options.tooltipBgColor.g number - Green component (0-255)
options.tooltipBgColor.b number - Blue component (0-255)
options.tooltipBgColor.a number - Alpha component (0-1)
tileArc object - Configuration for tile arcs (required)
tileArc.colorTileThresholdRed string '#ff0c4d' Color for values above red threshold
tileArc.colorTileThresholdYellow string '#ffff00' Color for values above yellow threshold but below red
tileArc.colorTileThresholdDefault string '#00ff00' Default color for values below yellow threshold
tileArc.colorTileBg string '#ddd' Background color for unfilled tiles
tileArc.fillStyle enum 'filled' Fill style for tiles (filled, dotted, dashed, outlined)
tileArc.borderColor string '#000000' Border color for outlined tiles
tileArc.borderThickness number 1 Border thickness for outlined tiles
tileArc.tiles number 10 Number of tiles to display
tileArc.isTileColorGradient boolean true Whether to use gradient coloring for tiles
tileArc.gradientType string 'tile' Type of gradient to use ('full' or 'tile')
tileArc.tickEveryNThStep number 0 Step size for tick labels (0 means auto)
tileArc.toolTipLabel string 'Sum' Label for tile tooltip
tileArc.arcConfig object - Arc configuration for tiles
tileArc.arcConfig.padAngle number 2 Padding angle between arcs
tileArc.arcConfig.padRadius number 2 Padding radius for arcs
tileArc.arcConfig.cornerRadius number 5 Corner radius for arcs
primaryArcConfig object - Configuration for primary arc
primaryArcConfig.colorPrimaryBar string '#000000' Color for primary bar
primaryArcConfig.toolTipLabel string 'Primary' Label for primary tooltip
primaryArcConfig.arcConfig object - Arc configuration for primary arc
primaryArcConfig.arcConfig.padAngle number 0 Padding angle between arcs
primaryArcConfig.arcConfig.padRadius number 0 Padding radius for arcs
primaryArcConfig.arcConfig.cornerRadius number 5 Corner radius for arcs
primaryArcConfig.pointerPrimaryConfig object - Pointer configuration for primary value
primaryArcConfig.pointerPrimaryConfig.scale number 1 Scale factor for pointer size
primaryArcConfig.pointerPrimaryConfig.strokeScale number 1 Scale factor for pointer stroke width
primaryArcConfig.pointerPrimaryConfig.color string '#025bff' Color of the pointer
secondaryArcConfig object - Configuration for secondary arc
secondaryArcConfig.colorSecondaryBar string '#aaaaaa' Color for secondary bar
secondaryArcConfig.toolTipLabel string 'Secondary' Label for secondary tooltip
secondaryArcConfig.arcConfig object - Arc configuration for secondary arc
secondaryArcConfig.arcConfig.padAngle number 0 Padding angle between arcs
secondaryArcConfig.arcConfig.padRadius number 0 Padding radius for arcs
secondaryArcConfig.arcConfig.cornerRadius number 5 Corner radius for arcs
secondaryArcConfig.pointerSumConfig object - Pointer configuration for sum value
secondaryArcConfig.pointerSumConfig.scale number 1 Scale factor for pointer size
secondaryArcConfig.pointerSumConfig.strokeScale number 1 Scale factor for pointer stroke width
secondaryArcConfig.pointerSumConfig.color string '#0ed30e' Color of the pointer

Fill Style Options

The component supports different fill styles for tiles:

enum TileFillStyle {
  FILLED = "filled",
  DOTTED = "dotted",
  DASHED = "dashed",
  OUTLINED = "outlined"
}

Advanced Usage Examples

With Custom Formatters

import { GaugeChart } from '@darkvoicegit/gauge-chart';

function MyComponent() {
  // Format days with hours and minutes
  const formatDayHourMinute = (value) => {
    const days = Math.floor(value);
    const hours = Math.floor((value - days) * 8); // Assuming 8-hour workdays
    const minutes = Math.floor(((value - days) * 8 - hours) * 60);
    
    return `${days} d, ${hours} h, ${minutes} m`;
  };

  // Format value with day unit
  const formatDay = (value) => `${value} d`;

  return (
    <GaugeChart
      size="default"
      primary={5.75}
      secondary={2.25}
      unit={formatDay}
      unitTickFormatter={formatDayHourMinute}
      options={{
        thresholdYellow: 7,
        thresholdRed: 10,
        enableToolTip: true,
        enableUnitTicks: true
      }}
      tileArc={{
        tiles: 10,
        colorTileThresholdDefault: '#00ff00',
        colorTileThresholdYellow: '#ffff00',
        colorTileThresholdRed: '#ff0c4d'
      }}
    />
  );
}

With Custom Styling

import { GaugeChart, TileFillStyle } from '@darkvoicegit/gauge-chart';

function MyComponent() {
  return (
    <GaugeChart
      size="m"
      primary={40}
      secondary={35}
      options={{
        thresholdYellow: 60,
        thresholdRed: 80,
        enableToolTip: true,
        tickLabelColor: '#ffffff',
        tickColor: '#777777',
        circleScale: 0.5,
        tickFontsize: '1rem',
        tickRadiusScale: 1.12
      }}
      tileArc={{
        tiles: 10,
        colorTileThresholdDefault: '#00ff00',
        colorTileThresholdYellow: '#ffff00',
        colorTileThresholdRed: '#ff0c4d',
        colorTileBg: '#ddd',
        fillStyle: TileFillStyle.DASHED,
        borderColor: '#000000',
        borderThickness: 1,
        isTileColorGradient: true,
        gradientType: 'tile',
        arcConfig: {
          cornerRadius: 5,
          padRadius: 2,
          padAngle: 2
        },
        toolTipLabel: 'Total'
      }}
      primaryArcConfig={{
        colorPrimaryBar: '#000000',
        pointerPrimaryConfig: {
          color: '#025bff',
          scale: 1,
          strokeScale: 1
        },
        arcConfig: {
          cornerRadius: 5,
          padRadius: 0,
          padAngle: 0
        },
        toolTipLabel: 'Primary'
      }}
      secondaryArcConfig={{
        colorSecondaryBar: '#aaaaaa',
        pointerSumConfig: {
          color: '#0ed30e',
          scale: 1,
          strokeScale: 1
        },
        arcConfig: {
          cornerRadius: 5,
          padRadius: 0,
          padAngle: 0
        },
        toolTipLabel: 'Secondary'
      }}
    />
  );
}

Customization Examples

Changing Thresholds and Colors

<GaugeChart
  primary={40}
  secondary={35}
  options={{
    thresholdYellow: 60,  // Yellow warning starts at 60%
    thresholdRed: 80,     // Red warning starts at 80%
  }}
  tileArc={{
    colorTileThresholdDefault: '#00ff00',  // Green for normal values
    colorTileThresholdYellow: '#ffff00',   // Yellow for warning values
    colorTileThresholdRed: '#ff0c4d',      // Red for critical values
  }}
/>

Customizing Tooltips

<GaugeChart
  primary={40}
  secondary={35}
  options={{
    enableToolTip: true,  // Enable tooltips
  }}
  tileArc={{
    toolTipLabel: 'Total',  // Label for tile tooltip
  }}
  primaryArcConfig={{
    toolTipLabel: 'Booked',  // Label for primary tooltip
  }}
  secondaryArcConfig={{
    toolTipLabel: 'Planned',  // Label for secondary tooltip
  }}
/>

Customizing Tile Appearance

<GaugeChart
  primary={40}
  secondary={35}
  size="xxs" // smaller preset, keeps whitespace tight
  tileArc={{
    tiles: 15,  // Number of tiles
    fillStyle: TileFillStyle.DOTTED,  // Dotted fill style
    borderColor: '#000000',  // Border color
    borderThickness: 2,  // Border thickness
    isTileColorGradient: true,  // Use gradient coloring
    gradientType: 'full',  // Full gradient type
  }}
/>

Customizing Pointers

<GaugeChart
  primary={40}
  secondary={35}
  primaryArcConfig={{
    pointerPrimaryConfig: {
      color: '#025bff',  // Blue pointer for primary
      scale: 1.2,  // Larger pointer
      strokeScale: 1.5  // Thicker stroke
    }
  }}
  secondaryArcConfig={{
    pointerSumConfig: {
      color: '#0ed30e',  // Green pointer for secondary
      scale: 1,  // Normal size
      strokeScale: 1  // Normal stroke width
    }
  }}
/>

Technologies

This project is built with:

  • React - UI library
  • TypeScript - Type-safe JavaScript
  • D3.js - Data visualization library
  • Material-UI - UI component library (for the demo)
  • Vite - Build tool and development server
  • Vitest - Testing framework

License

MIT

About

DarkvoiceGit.github.io/gaugeChart

Resources

Readme
Activity

Stars

0 stars

Watchers

1 watching

Forks

0 forks
Report repository

Releases 3

v2.0.1 Latest
Feb 26, 2026
+ 2 releases

Packages

 
 
 

Contributors

Languages