Registry / web-framework / react-odometerjs

react-odometerjs

JSON →
library3.1.3jsnpmunverified

React Odometer.js is a wrapper component that integrates the Odometer.js library into React applications, providing animated numerical counters. The current stable version is 3.1.3. While it doesn't follow a strict release cadence, updates appear to coincide with significant React API changes or new features, such as the adoption of hooks in v3.0.0 for React 16.8+. Its primary differentiator is simplifying the use of Odometer.js within a React ecosystem, abstracting away direct DOM manipulation typically required by the underlying library. It ships with TypeScript types, enhancing developer experience and type safety. A key aspect of its usage is managing server-side rendering (SSR) environments like Next.js or Gatsby, where dynamic imports are necessary to prevent issues with Odometer.js's reliance on the browser's `document` object.

npm install react-odometerjs
INSTALL
IMPORT
SIG · REACT-ODOMETERJS
R
react-odometerjs
web-frameworkjavascriptv3.1.3
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Odometer
import Odometer from 'react-odometerjs';
import { Odometer } from 'react-odometerjs'; import * as Odometer from 'react-odometerjs';
The `Odometer` component is exported as a default export. Named or namespace imports for the component will fail.
Odometer (CommonJS)
(Use ESM import)
const Odometer = require('react-odometerjs');
While `react-odometerjs` is designed for ESM `import` statements, developers sometimes attempt to use CommonJS `require`. This can lead to issues in modern environments; prefer ESM imports.
OdometerProps
import type { OdometerProps } from 'react-odometerjs';
import { OdometerProps } from 'react-odometerjs';
For TypeScript projects, the component's props interface `OdometerProps` can be imported for type checking. Use `import type` to ensure it's a type-only import, preventing runtime overhead.

This example demonstrates how to integrate `react-odometerjs` into a React component, updating its value after a delay to show the animation. It also highlights basic styling and essential CSS theme import requirements.

import React, { useEffect, useState } from 'react'; import Odometer from 'react-odometerjs'; // To use themes, you must install the original 'odometer' package: // npm install odometer // Then, import the desired theme's CSS file. Example for default theme: import 'odometer/themes/odometer-theme-default.css'; const OdometerExample = () => { const [value, setValue] = useState(1234); const [isMounted, setIsMounted] = useState(false); // State to ensure Odometer is mounted on client-side useEffect(() => { // This ensures the Odometer component is only rendered client-side, // which is crucial for Odometer.js as it relies on the 'document' object. // For SSR frameworks, more robust dynamic imports are needed (see warnings). setIsMounted(true); const timeoutId = setTimeout(() => setValue(4321), 2000); return () => { clearTimeout(timeoutId); }; }, []); // Render a placeholder or nothing if not mounted to prevent SSR issues if (!isMounted) { return <div>Loading counter...</div>; } return ( <div style={{ padding: '20px', fontFamily: 'Arial, sans-serif' }}> <h1>Animated Counter Example</h1> <p>Watch the number change after 2 seconds:</p> <Odometer value={value} format="(.ddd),dd" // Example format: thousands separator and two decimal places (not shown here as value is integer) theme="default" // Corresponds to 'odometer-theme-default.css' animation="count" // Simple counting animation duration={1500} // Animation duration in milliseconds style={{ fontSize: '4em', fontWeight: 'bold', color: '#007bff' }} /> <p style={{ marginTop: '20px' }}>Current value: {value}</p> </div> ); }; export default OdometerExample;
Debug
Known issues
breakingMinimum React version increased to 16.8.0 due to the adoption of React Hooks, which are used internally by `react-odometerjs`.
fix
Upgrade your `react` and `react-dom` packages to at least `16.8.0`.
affects: >=3.0.0
breakingOdometer options are now passed directly as props to the component, rather than nested within an `options` object.
fix
Refactor usage from `<Odometer value={1234} options={{ format: '(.ddd),dd' }} />` to `<Odometer value={1234} format='(.ddd),dd' />`.
affects: >=2.0.0
deprecatedThe `selector` prop was removed as it had no effect when `auto: false`, which is the default configuration for this React wrapper.
fix
Remove the `selector` prop; the component now manages its own DOM element selection internally.
affects: >=3.1.0
gotchaWhen using `react-odometerjs` with Server-Side Rendering (SSR) frameworks like Next.js or Gatsby, the underlying `Odometer.js` library directly accesses the browser's `document` object, leading to 'document is not defined' errors during server builds.
fix
Wrap the `react-odometerjs` component import with a dynamic import and `ssr: false` option. Refer to the Next.js or Gatsby integration examples in the documentation for specific implementation details.
affects: *
gotchaTo display correctly, `react-odometerjs` requires an Odometer.js CSS theme file to be manually imported into your application's `head` or component stylesheet.
fix
Ensure you have installed the `odometer` npm package (`npm install odometer`) and then add a `<link rel="stylesheet" href="odometer-theme-default.css" />` to your `index.html` or import a theme CSS file in your main application entry point (e.g., `import 'odometer/themes/odometer-theme-default.css';`).
affects: *
gotchaRuntime Prop Types are no longer bundled with the npm package since v2.1.0, relying instead on TypeScript types for type checking.
fix
For type checking, rely on TypeScript's built-in type inference or import the `OdometerProps` interface; do not expect runtime PropTypes to be present.
affects: >=2.1.0
Errors
Common errors & fixes
ReferenceError: document is not defined
Attempting to render `react-odometerjs` on the server-side in an SSR environment (e.g., Next.js, Gatsby) without dynamically importing it.
fix
Use a dynamic import for the `Odometer` component with `ssr: false`. Example for Next.js: `const Odometer = dynamic(import('react-odometerjs'), { ssr: false, loading: () => 0 });`
Objects are not valid as a React child (found: object with keys {format}). If you meant to render a collection of children, use an array instead.
Passing Odometer options as an object to an `options` prop, which was deprecated and removed in v2.0.0.
fix
Pass Odometer options directly as props to the component. Change `<Odometer value={1234} options={{ format: '(.ddd),dd' }} />` to `<Odometer value={1234} format="(.ddd),dd" />`.
TypeError: Cannot read properties of null (reading 'style') OR Odometer is not defined
The Odometer.js library or its React wrapper attempts to access DOM elements before the required CSS theme is loaded or the component is properly mounted, or due to incorrect theme application.
fix
Ensure that the `odometer` npm package is installed (`npm install odometer`) and a theme CSS file (e.g., `odometer/themes/odometer-theme-default.css`) is properly imported and applied globally or in the component's scope. Also, confirm the `theme` prop, if used, matches the imported CSS.
Error: Invalid hook call. Hooks can only be called inside of the body of a function component.
`react-odometerjs` v3.0.0+ utilizes React Hooks internally, but your project's `react` and `react-dom` peer dependencies are older than the required 16.8.0 version.
fix
Update your `react` and `react-dom` packages in your project to version `16.8.0` or higher to support React Hooks.
Upgrade
Version history
3.1.3latest on npm
Audit
Dependencies
reactrequiredPeer dependency for React applications, minimum version 16.8.0 for hooks.
react-domrequiredPeer dependency for rendering React components.
Agent activity
4 hits · last 30 days
node
4
Resources
react-odometerjs — npm install react-odometerjs · libregistry