use-count-up
    TypeScript icon, indicating that this package has built-in type declarations

    3.0.1 • Public • Published

    use-count-up

    NPM version Weekly downloads Code Coverage Bundle Size


    React/React Native component and hook to animate
    counting up or down to a number


    Key features

    🏆 Lighter implementation and smaller bundle size in comparison with similar feature solutions
    🎏 Declarative API (no more imperative calls to start() and update())
     📱  React Native support for iOS and Android
    🌳 Tree-shakable
     🗄️ Server-side rendering (SSR) compatibility

    Installation

    yarn add use-count-up
    

    Demo

    Check the React demo on CodeSandbox and React Native demo on Expo Snack to get started.

    Component basic usage

    import { CountUp } from 'use-count-up'
    
    const MyComponent = () => <CountUp isCounting end={1320} duration={3.2} />

    The CountUp component should be wrapped in a Text component when used in a React Native project like so:

    import { Text } from 'react-native'
    import { CountUp } from 'use-count-up'
    
    const MyComponent = () => (
      <Text>
        <CountUp isCounting end={1320} duration={3.2} />
      </Text>
    )

    Hook basic usage

    The hook accepts the same properties as the component. The usage for React and React Native is the same.

    import { useCountUp } from 'use-count-up'
    
    const MyComponent = () => {
      const { value } = useCountUp({
        isCounting: true,
        end: 1320,
        duration: 3.2,
      })
    
      return value
    }

    Props

    The component and the hook accept the same props. They are fully interchangeable.

    Prop Name Type Default Description
    isCounting boolean false Play and pause counting animation
    start number 0 Initial value
    end number - Target value
    duration number - Animation duration in seconds. Defaults to 2 seconds if end is set
    decimalPlaces number - Number of decimal places after the decimal separator. Defaults to the max decimal places count from start and end props
    decimalSeparator string - Decimal separator character
    thousandsSeparator string - Thousands separator character
    easing string | function easeOutCubic Type: easeOutCubic | easeInCubic | linear | easing func
    Easing function to control the animation progress
    formatter function - Type: (value: number) => number | string | node
    A function that formats the output value. It has the highest priority so all other formatting options are ignored
    updateInterval number 0 Update interval in seconds. Determines how often the animated value will change. When set to 0 the value will update on each key frame
    children function - Type: ({ value: number, reset: () => void }) => number | string | node
    CountUp component - children prop
    onComplete function - Type: () => void | {shouldRepeat: boolean, delay: number}
    On complete handler. Repeat animation by returning an object with shouldRepeat equals true and delay in seconds.
    onUpdate function - Type: (currentValue: number | string | node) => void
    On value update event handler

    Return values

    The hook returns the current count up value and reset method to reset the animation.

    import { useCountUp } from 'use-count-up'
    
    const { value, reset } = useCountUp({ isCounting: true })

    The component's children render function will receive as props the current count up value and reset method to reset the animation.

    import { CountUp } from 'use-count-up'
    
    const MyComponent = () => (
      <CountUp isCounting>{({ value, reset }) => value}</CountUp>
    )

    Why use toLocaleString with formatter

    Number formatting varies per language group. For example, the number 3842.45 in German will be formatted as 3.842,45 whereas in British English it will be 3,842.45 (spot the different decimal and thousands separators). Number.toLocaleString() is a built-in JS method that returns a string with a language-sensitive representation of the number. The basic implementation of the method will detect the default locale that is set up on the user's computer and will format the number accordingly. The browser support for toLocaleString is incredibly good.

    If you expect variance in the geographical/country distribution of your users, then this is a must. The simplest way to use toLocaleString with the Count up component or hook is to use the formatter prop, like so:

    import { CountUp } from 'use-count-up'
    
    const MyComponent = () => (
      <CountUp
        isCounting
        end={1320}
        formatter={(value) => value.toLocaleString()}
      />
    )

    toLocaleString method accepts an object with two parameters, locale and options, which allows further customization of the number value. Setting up the first parameter, locale, allows the use of a specific locale and fallback option. The second parameter, options, will let you format the value in a custom way. For example, you may choose to add a min and max number of decimal places, or set currency. Keep in mind though that the locale and options arguments are not supported in all browsers.

    Recipes

    Reset animation

    Pass a key prop to CountUp component and change it when the animation should repeat. It can be also used when a change of start or end value should start the animation over.

    import { CountUp } from 'use-count-up'
    
    const MyComponent = ({ end }) => <CountUp isCounting end={end} key={end} />

    Repeat animation on completion

    Return from the onComplete handler an object with key shouldRepeat: true. Optionally the delay before repeating can be set. In the example below the animation will be repeated in 2 seconds

    import { CountUp } from 'use-count-up'
    
    const onComplete = () => {
      // do your stuff here
      return { shouldRepeat: true, delay: 2 }
    }
    
    const MyComponent = () => (
      <CountUp isCounting end={4378.2} onComplete={onComplete} />
    )

    Count up to infinity

    Don't provide end and duration props. start prop can be set to any value

    import { CountUp } from 'use-count-up'
    
    const MyComponent = () => <CountUp isCounting start={1024.4} />

    Count up/down n-seconds

    Set the easing to "linear" and duration to the seconds it should count up/down. The updateInterval can be set to 1, so it updates once every second. Here is an example of a 10-second count-down:

    import { CountUp } from 'use-count-up'
    
    const MyComponent = () => (
      <CountUp
        isCounting
        start={10}
        end={0}
        duration={10}
        easing="linear"
        updateInterval={1}
        onUpdate={(currentValue) => {
          // it will fire once every second
        }}
      />
    )

    Install

    npm i use-count-up

    DownloadsWeekly Downloads

    16,801

    Version

    3.0.1

    License

    MIT

    Unpacked Size

    27.5 kB

    Total Files

    12

    Last publish

    Collaborators

    • vydimitrov