react-slot-counter

react-slot-counter is a feature-rich React component that displays numbers and strings with an engaging slot machine animation effect.

Features

• Flexible Inputs: Support for displaying numbers, strings, and JSX elements. You can even use a combination of these in a single slot counter instance!
• Animated Changes: Only the characters that change get animated, bringing life and motion to your app's interface.
• Customize Animation Settings: Control the duration of the animation, or decide whether to start the animation automatically upon mounting.
• Sequential Animation Mode: A unique feature that provides the option to animate the numbers incrementally or decrementally from the start value to the target value, rather than a random animation.
• Monospace Font Support: The useMonospaceWidth prop ensures that all numeric characters occupy the same horizontal space as they would in a monospace font.
• Infinite List Appearance: Option to make the list appear as continuous, seamlessly connecting the end of the target character to the beginning.
• Style Customization: Easily add custom styles to the characters, separators, and overall container. You can even customize the class name for the slot value.
• Ref Support: Control the animation start with a ref for increased flexibility.

Immerse your users in an interactive, engaging, and enjoyable experience with react-slot-counter. Whether you're displaying user scores, loading status, or real-time data, react-slot-counter adds that extra 'spin' to your numbers and strings.

Installation

To install the package, run the following command:

npm install react-slot-counter

Usage

Import SlotCounter and use it in your component. Here's a simple example:

import React from 'react';
import SlotCounter from 'react-slot-counter';

function App() {
  return (
    <>
      <SlotCounter value={123456} />
      <SlotCounter value={36.5} />
      <SlotCounter value="1,234,567" />
      <SlotCounter value={['1', '2', '3', '4', '5', '6']} />
      <SlotCounter value="??????" />
    </>
  );
}

export default App;

Demo

For more examples of usage and available options, check out the demo page.

Props

| Prop | Type | Default | Description | Version | | ----------------------- | ----------------------------------------------------- | -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | | value (required) | number | string | string[] | JSX.Element[] | | The value to be displayed. It can be a number or a string with numbers and commas. | JSX.Element: 1.8.0 | | startValue | number | string | string[] | JSX.Element[] | | The initial value to be displayed before the animation starts. It sets the beginning of the slot machine animation. | 1.7.0 | | startValueOnce | boolean | false | If set to true, the animation starts from the startValue only for the first render. For subsequent animations, it starts from the last value. | 1.10.0 | | duration | number | 0.7 | The duration of the animation in seconds. | | | dummyCharacters | string[] | JSX.Element[] | Defaults to random numbers from 0 to 9 | An array of dummy characters to be used in the animation. | | | dummyCharacterCount | number | 6 | The number of dummy characters to be displayed in the animation before reaching the target character. | | | autoAnimationStart | boolean | true | Determines whether the animation should start automatically when the component is first mounted. | | | animateUnchanged | boolean | false | Determines whether to animate only the characters that have changed. | | | hasInfiniteList | boolean | false | Determines whether the list should appear as continuous, with the end of the target character seamlessly connected to the beginning. | 1.4.2 | | containerClassName | string | | The class name of container. | | | charClassName | string | | The class name of each character. | | | separatorClassName | string | | The class name of the separator character (. or ,). | | | valueClassName | string | | The class name for the value of the slot, making it possible to customize the styling and visibility of the value. | 1.4.3 | | sequentialAnimationMode | boolean | false | Determines if the animation should increment or decrement sequentially from the startValue to value instead of random animation. | 1.9.0 | | useMonospaceWidth | boolean | false | Ensures that all numeric characters occupy the same horizontal space, just like they would in a monospace font. | 1.9.0 | | debounceDelay | number | 0 | Specifies the delay in milliseconds for debouncing animations. When the value changes rapidly, it allows the animation to execute smoothly. | 1.11.0 |

Ref

You can access the SlotCounter component using a ref. This ref can be used to start the animation of the component.

| Method | Description | | ---------------- | ------------------------------------ | | startAnimation | Start the animation of the component |

The startAnimation method accepts an optional object with the following properties:

• duration: The duration of the animation in seconds. Overrides the duration prop.
• dummyCharacterCount: The number of dummy characters to be displayed in the animation before reaching the target character. Overrides the dummyCharacterCount prop.
• direction: This option determines the direction of the slot machine animation. The accepted values are bottom-top and top-bottom. The default value is bottom-top. If bottom-top is chosen, the animation will start from the bottom and move towards the top. If top-bottom is chosen, the animation will start from the top and move downwards.

Example:

import React, { useRef } from 'react';
import SlotCounter, { SlotCounterRef } from 'react-slot-counter';

function App() {
  const counterRef = useRef < SlotCounterRef > null;

  const handleStartClick = () => {
    counterRef.current?.startAnimation();
  };

  return (
    <>
      <SlotCounter value={123456} ref={counterRef} />
      <button onClick={handleStartClick}>Start</button>
    </>
  );
}

export default App;

Contributing

Contributions are always welcome!

Support Us

If you find this library useful, consider giving us a star on GitHub! Your support is greatly appreciated and it helps the project grow.

License

This project is licensed under the MIT License.