React Gauge Component

Common errors

• ReferenceError: document is not defined

  cause Attempting to render `react-gauge-component` in a Server-Side Rendering (SSR) environment without disabling SSR for the component.
  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.

• TypeError: Cannot read properties of undefined (reading 'current')

  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.
  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.

• Error: Invalid hook call. Hooks can only be called inside of the body of a function 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.
  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.

Warnings

• breaking 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.
  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.
• gotcha 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.
  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.
• gotcha Incorrect or incompatible React and React-DOM peer dependencies can lead to runtime errors or unexpected behavior. The component relies on specific React features.
  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.

Install

• npm install react-gauge-component npm
• yarn add react-gauge-component yarn
• pnpm add react-gauge-component pnpm

Imports

• GaugeComponent
  wrong:

  const GaugeComponent = require('react-gauge-component');

  correct:

  import GaugeComponent from 'react-gauge-component';

  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.
• GaugeComponent (Named)
  wrong:

  import GaugeComponent from 'react-gauge-component';

  correct:

  import { GaugeComponent } from 'react-gauge-component';

  Some build tools or environments might prefer or enforce named imports, especially if the module is internally using `export { GaugeComponent }`.
• GaugeComponent (Next.js Dynamic Import)
  wrong:

  import GaugeComponent from 'react-gauge-component';

  correct:

  import dynamic from 'next/dynamic';
  const GaugeComponent = dynamic(() => import('react-gauge-component'), { ssr: false });

  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.

Quickstart

This quickstart demonstrates installing the package and rendering a basic gauge component with custom colored arcs, a value, and a formatted label.

import React from 'react';
import GaugeComponent from 'react-gauge-component';

function MyGauge() {
  return (
    <div style={{ width: '300px', height: 'auto' }}>
      <GaugeComponent
        arc={{
          width: 0.2,
          padding: 0.005,
          cornerRadius: 1,
          subArcs: [
            { limit: 15, color: '#EA4228', showPoint: true },
            { limit: 35, color: '#F5CD19', showPoint: true },
            { limit: 65, color: '#5BE12C', showPoint: true },
            { limit: 100, color: '#444444', showPoint: true }
          ]
        }}
        value={75}
        labels={{
          valueLabel: {
            formatTextValue: value => value + ' km/h'
          }
        }}
      />
    </div>
  );
}

export default MyGauge;