{"id":15186,"library":"react-gauge-component","title":"React Gauge Component","description":"react-gauge-component is a customizable React component designed for displaying gauge charts, often used for data visualization like speedometers or Grafana-style gauges. The current stable version is 2.0.28, with frequent patch and minor updates within the 2.x series. It was forked from `@Martin36/react-gauge-chart` and significantly re-architected in its v2 release to provide enhanced customization options and modern React compatibility. Key differentiators include robust TypeScript support, a flexible API for segment and value rendering, and an online sandbox editor for easy configuration. It requires React 16.8.2 or newer as a peer dependency, ensuring broad compatibility with contemporary React ecosystems.","status":"active","version":"2.0.28","language":"javascript","source_language":"en","source_url":"https://github.com/antoniolago/react-gauge-component","tags":["javascript","gauge","chart","speedometer","grafana gauge","react","typescript"],"install":[{"cmd":"npm install react-gauge-component","lang":"bash","label":"npm"},{"cmd":"yarn add react-gauge-component","lang":"bash","label":"yarn"},{"cmd":"pnpm add react-gauge-component","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for rendering React components.","package":"react","optional":false},{"reason":"Required for rendering React components to the DOM.","package":"react-dom","optional":false}],"imports":[{"note":"While the README implies both default and named imports work, the canonical way for components is often a default export. Prefer named imports for library functions.","wrong":"const GaugeComponent = require('react-gauge-component');","symbol":"GaugeComponent","correct":"import GaugeComponent from 'react-gauge-component';"},{"note":"Some build tools or environments might prefer or enforce named imports, especially if the module is internally using `export { GaugeComponent }`.","wrong":"import GaugeComponent from 'react-gauge-component';","symbol":"GaugeComponent (Named)","correct":"import { GaugeComponent } from 'react-gauge-component';"},{"note":"This component manipulates the DOM, which requires a browser environment. For Next.js or other SSR frameworks, dynamic import with `ssr: false` is essential to prevent 'document is not defined' errors.","wrong":"import GaugeComponent from 'react-gauge-component';","symbol":"GaugeComponent (Next.js Dynamic Import)","correct":"import dynamic from 'next/dynamic';\nconst GaugeComponent = dynamic(() => import('react-gauge-component'), { ssr: false });"}],"quickstart":{"code":"import React from 'react';\nimport GaugeComponent from 'react-gauge-component';\n\nfunction MyGauge() {\n return (\n
\n value + ' km/h'\n }\n }}\n />\n
\n );\n}\n\nexport default MyGauge;\n","lang":"typescript","description":"This quickstart demonstrates installing the package and rendering a basic gauge component with custom colored arcs, a value, and a formatted label."},"warnings":[{"fix":"Refer to the official API documentation for v2.x (API.md on GitHub) and the demo page to update component props and structure. The core API for `arc`, `value`, and `labels` has changed.","message":"The package underwent a major refactor and API overhaul with the release of v2.0.20. Code written for v1.x is not directly compatible with v2.x and requires migration.","severity":"breaking","affected_versions":">=2.0.20"},{"fix":"Use dynamic imports with `ssr: false` (e.g., `const GaugeComponent = dynamic(() => import('react-gauge-component'), { ssr: false });`) to ensure the component is only loaded on the client-side.","message":"When using `react-gauge-component` within Server-Side Rendering (SSR) frameworks like Next.js, importing the component directly will lead to 'document is not defined' errors because the component expects a browser DOM environment.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure your project's `react` and `react-dom` versions satisfy the peer dependency requirements (`^16.8.2 || ^17.0 || ^18.x || ^19.x`). Use `npm install` or `yarn install` to resolve peer dependency warnings.","message":"Incorrect or incompatible React and React-DOM peer dependencies can lead to runtime errors or unexpected behavior. The component relies on specific React features.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"For Next.js, use `const GaugeComponent = dynamic(() => import('react-gauge-component'), { ssr: false });`. For other SSR frameworks, ensure the component is only loaded client-side.","cause":"Attempting to render `react-gauge-component` in a Server-Side Rendering (SSR) environment without disabling SSR for the component.","error":"ReferenceError: document is not defined"},{"fix":"This is often related to SSR issues. Apply dynamic import with `ssr: false` as described in the warnings. Also, ensure React and React-DOM peer dependencies are correctly installed and compatible.","cause":"This error often indicates that a React ref is being accessed before it's attached to a DOM element, which can happen if the component tries to render too early or if there's a problem with the rendering lifecycle in an SSR context.","error":"TypeError: Cannot read properties of undefined (reading 'current')"},{"fix":"Check for duplicate React installations using `npm ls react` or `yarn why react`. Ensure `react` and `react-dom` peer dependencies are met and are singular in your dependency tree. Re-evaluate any custom rendering logic around the gauge component.","cause":"This common React error can occur if there are multiple versions of React loaded in your application, or if the rules of hooks are violated, sometimes indirectly due to incompatible peer dependencies.","error":"Error: Invalid hook call. Hooks can only be called inside of the body of a function component."}],"ecosystem":"npm"}