reeller

Cuberto Reeller

Flexible, powerful and modern library for creating the running horizontal blocks effect, also known as ticker or the «marquee effect».

The library uses GSAP, IntersectionObserver and ResizeObserver to achieve the best performance results.

⚠️ Notice: This library is currently in beta.

Dependencies

GSAP v3 (https://greensock.com/gsap/)

Quick start

Install from NPM

Reeller requires GSAP library to work.

npm install gsap --save
npm install reeller --save

Import GSAP, Reeller and initialize it:

import Reeller from 'reeller';
import gsap from 'gsap';

Reeller.registerGSAP(gsap);

const reeller = new Reeller({
    container: '.my-reel',
    wrapper: '.my-reel-wrap',
    itemSelector: '.my-reel-item',
    speed: 10,
});

Use from CDN

If you don't want to include Reeller files in your project, you can use library from CDN:

<script src="https://unpkg.com/reeller@0/dist/reeller.min.js"></script>

Reeller requires GSAP to work. You need to import it above the Reeller if you didn't have it before:

<script src="https://cdnjs.cloudflare.com/ajax/libs/gsap/3.10.4/gsap.min.js"></script>
<script src="https://unpkg.com/reeller@0/dist/reeller.min.js"></script>
<script>
    var reeller = new Reeller.Reeller({
        container: '.my-reel',
        wrapper: '.my-reel-wrap',
        itemSelector: '.my-reel-item',
        speed: 10,
    });
</script>

Note: All modules (Reeller, Filler, ScrollerPlugin) will be imported into Reeller namespace when using from CDN, so you must use a prefix.

Options

You can configure Reeller via options.

The following options with defaults is available:

const reeller = new Reeller({
    container: null,
    wrapper: null,
    itemSelector: null,
    cloneClassName: '-clone',
    speed: 10,
    ease: 'none',
    initialSeek: 10,
    loop: true,
    paused: true,
    reversed: false,
    autoStop: true,
    autoUpdate: true,
    clonesOverflow: true,
    clonesFinish: false,
    clonesMin: 0,
});

Option	Type	Default	Description
container	string | HTMLElement	null	Required. Container element or selector.
wrapper	string | HTMLElement	null	Required. Inner element or selector.
itemSelector	string	null	Required. Items CSS selector.
cloneClassName	string	-clone	Class name of the new clones.
speed	number	10	Movement speed.
ease	string	'none'	Timing function. See gsap easing.
initialSeek	number	10	Initial seek of timeline.
loop	boolean	true	Loop movement.
pause	boolean	true	Initialize in paused mode.
reversed	boolean	false	Reverse mode.
autoStop	boolean	true	Use IntersectionObserver to auto stop movement.
autoUpdate	boolean	true	Use ResizeObserver to auto update clones number.
clonesOverflow	boolean	true	Create artificial overflow with clones.
clonesFinish	boolean	false	Bring the cycle of clones to an end.
clonesMin	boolean	0	Minimum number of clones.
plugins	Object	null	Options for plugins. See Plugins section.

API

Methods

Method	Description
reeller.resume()	Resumes movement.
reeller.pause()	Pauses movement.
reeller.reverse([reversed=true])	Set reversed moving.
reeller.invalidate()	Refresh GSAP Timeline.
reeller.update()	Calculates and sets the number of clones and update movement position.
reeller.refresh(update=true)	Fully refresh and update all clones and position. Use this only after adding or removing original items.
reeller.destroy(removeClones=true)	Destroy Reeller instance, detach all observers and remove clones.
Reeller.registerGSAP(gsap)	Static method to register the gsap library.
Reeller.use(...plugins)	Static method to register a plugins.

Properties

Property	Type	Description
reeller.paused	boolean	Indicates that the movement is stopped.
reeller.tl	Timeline	GSAP Timeline.
reeller.filler	Filler	Inner Filler instance. See Filler section.
reeller.options	ReellerOptions	Current Reeller options.
reeller.plugin	Object	Initialized plugins.

Events

Reeller comes with a useful events you can listen. Events can be assigned in this way:

reeller.on('update', () => {
    console.log('Reeller update happened!');
});

You can also delete an event that you no longer want to listen in these ways:

reeller.off('update');
reeller.off('update', myHandler);

Event	Arguments	Description
update	(reeller, calcData)	Event will be fired after update.
refresh	(reeller)	Event will be fired after refresh.
destroy	(reeller)	Event will be fired after destroy.

Plugins

Reeller support plugins to extend functionality.

At this moment there is only one plugin that comes with the official package: ScrollerPlugin.

This plugin allows you to attach movement to the scroll:

import {Reeller, ScrollerPlugin} from 'reeller';
import gsap from 'gsap';

Reeller.registerGSAP(gsap);
Reeller.use(ScrollerPlugin);

const reeller = new Reeller({
    container: '.my-reel',
    wrapper: '.my-reel-wrap',
    itemSelector: '.my-reel-item',
    speed: 10,
    plugins: {
        scroller: {
            speed: 1,
            multiplier: 0.5,
            threshold: 1,
        },
    },
});

The following options of ScrollerPlugin is available:

Option	Type	Default	Description
speed	number	1	Movement and inertia speed.
multiplier	number	0.5	Movement multiplier.
threshold	number	1	Movement threshold.
ease	string	'expo.out'	Timing function. See gsap easing.
overwrite	boolean	true	See gsap overwrite modes.
bothDirection	boolean	true	Allow movement in both directions.
reversed	boolean	false	Reverse scroll movement.
stopOnEnd	boolean	false	Stop movement on end scrolling.
scrollProxy	function	null	A function that returns the scroll position. Can be used in cases with custom scroll.

In cases with using of custom scroll libraries (e.g. smooth-scrollbar), you can use the scrollProxy option to return the current scroll position:

import Scrollbar from 'smooth-scrollbar';
import {Reeller, ScrollerPlugin} from 'reeller';
import gsap from 'gsap';

Reeller.registerGSAP(gsap);
Reeller.use(ScrollerPlugin);

const scrollbar = Scrollbar.init(document.querySelector('#my-scrollbar'));

const reeller = new Reeller({
    container: '.my-reel',
    wrapper: '.my-reel-wrap',
    itemSelector: '.my-reel-item',
    speed: 10,
    plugins: {
        scroller: {
            speed: 1,
            multiplier: 0.5,
            threshold: 1,
            scrollProxy: () => scrollbar.scrollTop,
        },
    },
});

Filler

Reeller library works on top of the Filler module. This is a separate tool for automatically calculating the number of clones and filling the container with them.

You can use only Filler (without Reeller) if you need to fill the whole space with clones, without movement, animations and GSAP:

import {Filler} from 'reeller';

const filler = new Filler({
    container: '.my-container',
    itemSelector: '.-my-item',
    cloneClassName: '-clone',
});

Options

Option	Type	Default	Description
container	string | HTMLElement	null	Required. Container element or selector.
itemSelector	string	null	Required. Items CSS selector.
wrapper	string | HTMLElement	null	Inner element or selector.
cloneClassName	string	'-clone'	Class name of the new clones.
autoUpdate	boolean	true	Use ResizeObserver to auto update clones number.
clonesOverflow	boolean	false	Create artificial overflow with clones.
clonesFinish	boolean	false	Bring the cycle of clones to an end.
clonesMin	boolean	false	Minimum number of clones.

Methods

Method	Description
filler.addClones(count, offset=0)	Creates and adds clones to end in the desired number from given offset.
filler.removeClones(count)	Removes the desired number of clones from the end.
filler.setClonesCount(count)	Sets the desired number of clones.
filler.getCalcData()	Returns a calculated data object (number of clones, widths, etc.)
filler.update()	Calculates and sets the number of clones.
filler.refresh(update=true)	Fully refresh and update all clones. Use this only after adding or removing original items.
filler.destroy(removeClones=true)	Destroy Filler instance, detach all observers and remove clones.

Properties

Property	Type	Description
filler.container	HTMLElement	Container element.
filler.wrapper	HTMLElement	Inner element.
filler.item	Array.<HTMLElement>	Items array.
filler.calcData	Object	Calculated data (number of clones, widths, etc.).
filler.options	ReellerOptions	Current Filler options.

Events

Event	Arguments	Description
update	(filler, calcData)	Event will be fired after update.
refresh	(filler)	Event will be fired after refresh.
destroy	(filler)	Event will be fired after destroy.

Examples of use

• Cuberto: Leading digital agency.
• Potion: Video email for top sales professionals.
• Weltio: More ways to grow your money.
• WorkJam: Drive Employee Engagement.
• Spendwisor: Make your shopping easier.
• Sleepiest: The Sleepiest App.
• Perform: Unlock workout superpowers.

License

The MIT License (MIT)