react-d3-speedometer

React library for showing speedometer like gauge using d3.

Note: v2.x is compatible with React v18. v1.x is compatible with React 17. Please use latest v0.x (v0.14.1 at the time of writing) if you are using React 16.

react-d3-speedometer

• Getting Started
• Configuration Options
• Examples
• FAQ
• Ports

Getting Started:

Install with yarn or npm.

Yarn:

yarn add react-d3-speedometer

npm:

npm install --save react-d3-speedometer

And, use it like

// import the component
import ReactSpeedometer from "react-d3-speedometer"
// and just use it
<ReactSpeedometer />

Slim Build:

There is a Slim build available without bundling d3. This project uses d3 micro bundles. If your project also uses d3 microbundles, you can opt for slim build. Necessary d3 dependencies required for slim build to work are - d3-array, d3-color, d3-ease, d3-format, d3-interpolate, d3-scale, d3-selection, d3-shape, d3-transition.

// sample slim build usage
import ReactSpeedometer from "react-d3-speedometer/slim"
// and use it
<ReactSpeedometer />

Live Examples

Configuration Options:

Examples

You can view Live Examples here

Default with no config - Live Example

<ReactSpeedometer />

With configurations - Live Example

<ReactSpeedometer
  maxValue={500}
  value={473}
  needleColor="red"
  startColor="green"
  segments={10}
  endColor="blue"
/>

Custom Segment Colors - Live Example

<ReactSpeedometer
  value={333}
  segments={5}
  segmentColors={[
    "#bf616a",
    "#d08770",
    "#ebcb8b",
    "#a3be8c",
    "#b48ead",
  ]}
  // startColor will be ignored
  // endColor will be ignored
/>

Custom Segment Labels - Live Example

  // 'customSegmentLabels' prop takes an array of 'CustomSegmentLabel' Object
  /*
  type CustomSegmentLabel = {
    text?: string
    position?: OUTSIDE/INSIDE
    fontSize?: string
    color?: string
  }
  */

  <ReactSpeedometer
    value={777}
    currentValueText="Happiness Level"
    customSegmentLabels={[
      {
        text: "Very Bad",
        position: "INSIDE",
        color: "#555",
      },
      {
        text: "Bad",
        position: "INSIDE",
        color: "#555",
      },
      {
        text: "Ok",
        position: "INSIDE",
        color: "#555",
        fontSize: "19px",
      },
      {
        text: "Good",
        position: "INSIDE",
        color: "#555",
      },
      {
        text: "Very Good",
        position: "INSIDE",
        color: "#555",
      },
    ]}
  />

Custom Segment Stops - Live Example

  <ReactSpeedometer
    customSegmentStops={[0, 500, 750, 900, 1000]}
    segmentColors={["firebrick", "tomato", "gold", "limegreen"]}
    value={333}
  />
  // `segments` prop will be ignored since it will be calculated from `customSegmentStops`
  // In this case there will be `4` segments (0-500, 500-750, 750-900, 900-1000)
/>

Fluid Width Example - Live Example

// Speedometer will take the width of the parent div (500)
// any width passed will be ignored
<div style={{
  width: "500px",
  height: "300px",
  background: "#EFEFEF"
}}>
  <ReactSpeedometer
    fluidWidth={true}
    minValue={100}
    maxValue={500}
    value={473}
    needleColor="steelblue"
  />
</div>

Needle Transition Example - Live Example

<ReactSpeedometer
  value={333}
  needleColor="steelblue"
  needleTransitionDuration={4000}
  needleTransition="easeElastic"
/>

Force Render component on props change - Live Example

// By default, when props change, only the value prop is updated and animated. 
// This is to maintain smooth visualization and to ignore breaking appearance changes like segments, colors etc. 
// You can override this behaviour by giving forceRender: true

// render a component initially
<ReactSpeedometer
  width={200}
  height={200}
/>
// Now, if given forceRender: true, and change the appearance all together, the component will rerender completely on props change
<ReactSpeedometer
  forceRender={true}
  segments={15}
  width={500}
  height={500}
/>

Needle Height Configuration Example - Live Example

<ReactSpeedometer
  value={333}
  needleHeightRatio={0.7}
/>

You can give a value between 0 and 1 to control the needle height.

Gradient Like Effect - Live Example

<ReactSpeedometer
  value={333}
  maxSegmentLabels={5}
  segments={1000}
/>

FAQ:

1. How to use with nextjs?

   react-d3-speedometer uses lodash-es dependency for better tree shaking. For nextjs, please use next-transpile-modules, so that ES module exports from lodash-es package is properly transpiled. You can also nextjs dynamic imports - https://nextjs.org/docs/advanced-features/dynamic-import#with-no-ssr

Please refer to this issue for more details on how to make this library work with next.js - #89

2. How to use with React 17?

   Please use latest v1.x (v1.0.0 at the time of writing). v1.x is compatible with React 17.

3. How to use with React 16?

   Please use latest v0.x (v0.14.x at the time of writing). v0.x is compatible with React 16.

Ports:

• Vue: vue-speedometer
• Svelte: svelte-speedometer

Todos:

• Test coverage (with enzyme)
• Convert entire code base to ES6
• Split core from lifecycles
• Typescript support

Tests:

react-d3-speedometer comes with a test suite using enzyme.

// navigate to root folder and run
npm test
// or 'yarn test' if you are using yarn

Feature Updates:

• [v1.0.0] React v17 support. d3 v6 support. Live Example

• [v0.14.0] valueTextFontWeight config to control font weight of current value

• [v0.10.0] Custom labels. Live Example

• [v0.9.0] Typescript support

• [v0.8.0] paddingHorizontal, paddingVertical configuration to control spacing around text. Live Example

• [v0.7.0] Custom segment stops. Live Example

• [v0.6.0] Custom segment colors. Live Example

Changelog:

View Changelog

Credits:

react-d3-speedometer was started as a react port of the following d3 snippet - http://bl.ocks.org/msqr/3202712. Component template was initially bootstrapped with React CDK. Also, many thanks to react and d3 ecosystem contributors.

Contributing:

PRs are welcome. Please create a issue/bugfix/feature branch and create an issue with your branch details. Probably I will create a similar branch in the upstream repo so that PRs can be raised against that branch instead of master. master-v0.x is the main branch for React 16 compatible changes.

Notes

• 1.x versions are compatible with React & React DOM Versions v17.x
• 0.x versions are compatible with React & React DOM Versions v16.x For every subsequent major react upgrade, react-d3-speedometer will be bumped to next major versions. For example 1.x will be compatible with React 17.x so on and so forth ...

For similar library for VueJS, please check out vue-speedometer.

For similar library for Svelte, please check out svelte-speedometer.

License:

MIT