Registry / web-framework / react-countup

react-countup

library6.5.3jsnpmunverified

react-countup is a React component that provides an easy-to-use wrapper around the CountUp.js library, enabling numerical value animations within React applications. As of version 6.5.3, the library is actively maintained, with frequent patch and minor releases primarily focused on dependency updates, bug fixes, and incorporating new features from the underlying countup.js library, such as `useIndianSeparators` and scroll spy enhancements. It offers both a declarative component API (<CountUp />), a flexible render prop pattern, and a `useCountUp` hook for more fine-grained imperative control over the animation instance. Key differentiators include its robust API for controlling animation duration, delay, decimal and grouping separators, prefixes/suffixes, easing functions, and scroll-triggered animations, abstracting away the direct CountUp.js instance management. It also ships with TypeScript types, enhancing developer experience in typed projects.

web-framework data

npm install react-countup

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · REACT-COUNTUP

react-countup

web-frameworkjavascriptv6.5.3

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

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 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

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

CountUp

✓ import { CountUp } from 'react-countup'

✗ import CountUp from 'react-countup'

CountUp is a named export, not a default export.

useCountUp

✓ import { useCountUp } from 'react-countup'

✗ const useCountUp = require('react-countup').useCountUp

The `useCountUp` hook is a named export for functional components and custom hooks, incompatible with CommonJS `require` for direct access to the hook as a function.

CountUpProps

✓ import type { CountUpProps } from 'react-countup'

Importing types for TypeScript usage to ensure correct prop definitions.

Demonstrates the primary ways to use react-countup: as a simple component, with a render prop for manual control, and using the `useCountUp` hook for imperative animation management, including handling dynamic `end` values with the `redraw` prop.

import React, { useState } from 'react'; import { CountUp, useCountUp } from 'react-countup'; const App: React.FC = () => { const [dynamicValue, setDynamicValue] = useState(500); // Example using the useCountUp hook for imperative control const { countUp, start, pauseResume, reset, update } = useCountUp({ start: 0, end: 100, delay: 1000, duration: 5, onStart: () => console.log('Hook animation started!'), onEnd: () => console.log('Hook animation ended!'), }); return ( <div> <h1>React CountUp Examples</h1> <h2>Simple Component:</h2> <CountUp start={0} end={2024} duration={3} delay={0.5} prefix="Year: " suffix="!" separator="," decimals={0} useEasing={true} onEnd={() => console.log('Component animation finished!')} /> <br /><br /> <h2>Render Prop Example:</h2> <CountUp start={500} end={1000} duration={2} delay={1} useGrouping={false}> {({ countUpRef, start: renderPropStart }) => ( <div> <span ref={countUpRef} /> <button onClick={renderPropStart}>Start Render Prop</button> </div> )} </CountUp> <br /><br /> <h2>Hook (Imperative Control):</h2> <div> <p>Current Hook Value: {countUp}</p> <button onClick={start}>Start Hook</button> <button onClick={pauseResume}>Pause/Resume Hook</button> <button onClick={reset}>Reset Hook</button> <button onClick={() => update(Math.random() * 500 + 100)}>Update Hook</button> </div> <br /><br /> <h2>Dynamic Value with 'redraw' prop:</h2> <button onClick={() => setDynamicValue(Math.floor(Math.random() * 1000))}> Change Value to: {dynamicValue} </button> <br /> <CountUp start={0} end={dynamicValue} duration={2} redraw={true} className="dynamic-counter" /> </div> ); }; export default App;

Debug

Known issues

breakingMajor version updates (v3, v4, v5, v6) typically introduce breaking changes in API, prop names, or component behavior. Always consult the specific version's release notes and migration guides on GitHub when upgrading across major versions.

fix

Review the GitHub release notes and README for your target major version to identify necessary code adjustments.

affects: >=3.0

gotchaThe `redraw` prop is essential for re-triggering the animation when the `end` value changes. If `redraw` is not set to `true`, the CountUp component will only display the new `end` value without animating from the previous value.

fix

Add the `redraw={true}` prop to your `CountUp` component if you intend for the animation to restart upon changes to its `end` prop.

affects: >=1.0

gotchaThe `v6.5.3` release note 'Exclude esm build' is ambiguous. While likely a fix for bundling, it could subtly alter ESM module resolution or availability, potentially affecting specific build toolchains or module loaders. If you encounter issues with ESM imports after updating, investigate your build configuration.

fix

If experiencing ESM import issues, verify your build system's module resolution and consider testing updates in a controlled environment to catch unexpected behaviors.

affects: >=6.5.3

gotchaWhen using react-countup in Server-Side Rendering (SSR) environments, you might encounter issues due to its reliance on browser-specific APIs for animation. While v6.3.2 included fixes for SSR conditions, careful implementation is still required.

fix

For SSR applications, consider dynamically importing the `CountUp` component or rendering it only on the client-side (e.g., using `typeof window !== 'undefined'` checks or a dedicated `NoSSR` component) to avoid issues.

affects: >=1.0

Errors

Common errors & fixes

Invariant Violation: Invalid hook call. Hooks can only be called inside of the body of a function component.

Attempting to use the `useCountUp` hook outside of a React function component or a custom hook.

fix

Ensure `useCountUp` is called directly within the body of a React function component or another custom hook, strictly adhering to React's Rules of Hooks.

TypeError: Cannot read properties of undefined (reading 'current') / Cannot access 'countUpRef' before initialization

This error typically occurs when attempting to access the `countUpRef` or other imperative methods from the render prop API before the component has fully mounted or when the ref is not yet assigned.

fix

Interact with the CountUp instance methods (e.g., `start`, `pauseResume`) only when the component is mounted and the ref is available, often within React's `useEffect` hook or event handlers that trigger after initial render.

CountUp animation does not restart when the numeric 'end' prop changes.

By default, the `CountUp` component does not re-animate if the `end` prop changes after its initial render; it simply updates the displayed value without animation.

fix

To make the animation restart when the `end` prop changes, you must explicitly add the `redraw` prop to the `CountUp` component: `<CountUp end={newValue} redraw />`.

Upgrade

Version history

6.5.3latest on npm

Audit

Dependencies

reactrequiredPeer dependency for React applications.

countup.jsrequiredCore animation engine that react-countup wraps.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/glennreyes/react-countup ↗

packagehttps://www.npmjs.com/package/react-countup ↗

homepagehttps://react-countup.now.sh/ ↗