react-smart-ticker

React Smart Ticker

React Smart Ticker is a React component that automatically displays text as a scrolling ticker/marquee when it overflows the container.

Demo

https://eugen-k.github.io/react-smart-ticker-demo/

Features

• Multiline support
• Can be used as a ticker/marquee for any element e.g. text, images, HTML blocks
• Optionally draggable
• Supports RTL
• Highly customizable
• Zero dependency

SmartTicker and SmartTickerDraggable component differences

SmartTicker

• uses CSS based animation
• can be played or paused by click

SmartTickerDraggable

• uses requestAnimationFrame() based animation
• draggable
• has backward animation
• can have a delay before animating back to the start position

[!IMPORTANT] For complex elements (e.g. images) is recommended to use SmartTicker component as browsers are performing better using CSS-based animation.

Installation

NPM

npm install react-smart-ticker --save

Yarn

yarn add react-smart-ticker

Usage

Import SmartTicker or SmartTickerDraggable to a file depending on intended use:

import { SmartTicker } from 'react-smart-ticker'

import { SmartTickerDraggable } from 'react-smart-ticker'

Or import them both:

import { SmartTicker, SmartTickerDraggable } from 'react-smart-ticker'

Then in your .jsx or .tsx file use it as a simple React component:

import { SmartTicker, SmartTickerDraggable } from 'react-smart-ticker'

const App = () => (
  <>
    <SmartTicker>Some text</SmartTicker>
    <SmartTickerDraggable>Some draggable text</SmartTickerDraggable>
  </>
)

export default App

Props

Prop Name	Type	Required	Default	Description
smart	boolean	No	true	Smart mode that determines if that's enough space to fit the content of the ticker, and if it's enough the animation will be turned off until the contents change
isText	boolean	No	true	Determines if the content contains only text which allows showing ellipses when text content isn't fitted into the container
multiLine	number	No	0	Determines the maximum amount of lines within a text content. Sets direction to "top"
waitForFonts	boolean	No	true	Run the calculation only when fonts are loaded
speed	number	No	60	Scrolling speed in pixels per second
delay	number	No	0	Delay before starting the animation (in milliseconds)
⚠️ delayBack	number	No	0	Delay before back animation (in milliseconds). Requires infiniteScrollView prop to be false ⚠️ SmartTickerDraggable prop only
⚠️ speedBack	number	No	200	Scrolling speed in pixels per second for back animation. Requires infiniteScrollView prop to be false ⚠️ SmartTickerDraggable prop only
iterations	number | "infinite"	No	"infinite"	Amount of animation iterations second
infiniteScrollView	boolean	No	true	Determines if the content will repeated one by one during scrolling animation
autoFill	boolean	No	false	Flag to determine if ticker content should be copied and fill in all the container's space
direction	"left" | "right" | "top" | "bottom"	No	"left"	The direction in which the ticker will be moving
rtl	boolean	No	false	Aligns text content to the right. The default direction of animation will be switched to 'right'
pauseOnHover	boolean	No	false	Pause animation on hover
playOnHover	boolean	No	false	Play animation on hover
⚠️ pauseOnClick	boolean	No	false	Pause animation on click ⚠️ SmartTicker prop only
⚠️ playOnClick	boolean	No	false	Play animation on click ⚠️ SmartTicker prop only
⚠️ disableDragging	boolean	No	false	Disables ticker dragging possibility ⚠️ SmartTickerDraggable prop only
recalcDeps	[]	No	[]	Array of dependencies that trigger recalculation of the component
disableSelect	boolean	No	false	Controls the possibility of a user to select text in a ticker
style	CSSProperties	No	null	Ticker component custom CSS styles
containerStyle	CSSProperties	No	null	Ticker container component custom CSS styles
forwardedRef	ForwardedRef	No	null	Forwareded Ref for controlling the animation state

Controlling the Play, Pause snd Reset States

The components provide methods for developers to control the ticker’s play, pause and resets state programmatically. These methods are accessible via forwardedRef and allow you to start, stop and reset the ticker based on your app’s requirements.

Exposed Methods

To enable control over play and pause, react-smart-ticker uses forwardRef. The component exposes the following methods:

• play(): Starts the ticker animation.
• pause(): Pauses the ticker animation.
• reset(isPaused: boolean): Resets the ticker animation. isPaused (true by default) flag sets the animation state after resetting.

Usage

To use these methods, you need to: 1. Create a reference using useRef. 2. Attach the ref to the SmartTicker component. 3. Call the play and pause methods directly from the ref.

Example

Here’s an example of setting up and using play and pause with react-smart-ticker:

import { useRef } from 'react';
import SmartTicker from 'react-smart-ticker';

function App() {
  // Create a ref to access SmartTicker methods
  const tickerRef = useRef<{
    play: () => void
    pause: () => void
    reset: (isPaused: boolean) => void
  }>(null)

  // Define handlers to control the ticker
  const handlePlay = () => {
    tickerRef.current?.play()
  }

  const handlePause = () => {
    tickerRef.current?.pause()
  }

  const handleReset = (isPaused: boolean = true) => {
    tickerRef.current?.reset(isPaused)
  }

  return (
    <div>
      <SmartTicker forwardedRef={tickerRef}>
        <p>Your ticker content goes here</p>
      </SmartTicker>

      <button onClick={() => { handlePlay() }}>Play</button>
      <button onClick={() => { handlePause() }}>Pause</button>
      <button onClick={() => { handleReset(true) }}>Reset (w/pause)</button>
    </div>
  )
}

export default App;

Licence

This project is licensed under the MIT License - see the LICENSE file for details.