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.

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:

importReellerfrom'reeller';importgsapfrom'gsap';Reeller.registerGSAP(gsap);constreeller=newReeller({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:

<scriptsrc="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:

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

Note: All modules (Reeller, Filler, ScrollerPlugin, DragPlugin) 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:

constreeller=newReeller({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.
paused	boolean	true	Initialize in paused mode.
reversed	boolean	false	Reverse mode.
autoPlay	boolean	true	Use IntersectionObserver to auto play/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 are two plugins that come with the official package: ScrollerPlugin and DragPlugin.

ScrollerPlugin

This plugin allows you to attach movement to the scroll:

import{Reeller,ScrollerPlugin}from'reeller';importgsapfrom'gsap';Reeller.registerGSAP(gsap);Reeller.use(ScrollerPlugin);constreeller=newReeller({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:

importScrollbarfrom'smooth-scrollbar';import{Reeller,ScrollerPlugin}from'reeller';importgsapfrom'gsap';Reeller.registerGSAP(gsap);Reeller.use(ScrollerPlugin);constscrollbar=Scrollbar.init(document.querySelector('#my-scrollbar'));constreeller=newReeller({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,},},});

DragPlugin

DragPlugin adds horizontal drag control with inertia:

import{Reeller,DragPlugin}from'reeller';importgsapfrom'gsap';Reeller.registerGSAP(gsap);Reeller.use(DragPlugin);constreeller=newReeller({container: '.my-reel',wrapper: '.my-reel-wrap',itemSelector: '.my-reel-item',speed: 10,plugins: {drag: {speed: 1,multiplier: 1,axis: 'y',invertAxis: true,changeDirection: true,inertiaMultiplier: 0.2,},},});

The following options of DragPlugin is available:

Option	Type	Default	Description
speed	number	1	Inertia duration in seconds.
multiplier	number	1	Drag movement multiplier.
threshold	number	50	Minimum release velocity in px/s required to start inertia.
inertiaMultiplier	number	0.2	Inertia distance multiplier.
activationDistance	number	3	Minimum pointer movement in px before drag starts.
maxVelocity	number	3000	Maximum release velocity in px/s used for inertia calculation.
ease	string	'expo.out'	Timing function. See gsap easing.
changeDirection	boolean	false	Change autoplay direction to match the last drag direction after release.
axis	'x' | 'y'	'x'	Pointer axis used for drag. Set 'y' when the reel is rotated by -90deg.
invertAxis	boolean	false	Invert drag direction on the selected axis. Useful with rotated reels.
target	string | HTMLElement | null	null	Drag target element or selector. Defaults to the Reeller container.
preventDefault	boolean	true	Prevent default pointer behaviour while dragging.

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';constfiller=newFiller({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)