Smooth, Responsive, Infinite Scrolling Carousel Plugin - GSAP Marquee

GSAP Marquee is a lightweight JavaScript/jQuery plugin that creates responsive, smooth, horizontal, endless-looping, marquee-style carousels using the GSAP animation library.

It's built to generate a fluid and marquee-like animation that feels much smoother than traditional CSS approaches. Useful for displaying content like logos, news feeds, stock price, or image galleries in a compact, continuous loop.

Features:

• Ticker-driven animation: Uses GSAP's ticker system for smooth 60fps scrolling performance.
• Accurate spacing calculations: Handles margins and gaps correctly using getBoundingClientRect measurements.
• Multiple instance support: Run several marquees on the same page without conflicts.
• Flexible direction control: Switch between left-to-right and right-to-left scrolling.
• Interactive pause modes: Pause on hover, click, or programmatically control playback.
• Responsive design: Automatically rebuilds on window resize events.
• Accessibility features: Support for reduced motion preferences and keyboard navigation.
• Loop or single-run modes: Choose continuous looping or single-pass animation.

How to use it:

1. Include GSAP and the GSAP Marquee library in your project. The library supports both vanilla JavaScript and jQuery implementations:

<!-- GSAP Library is Required -->
<script src="/path/to/cdn/gsap.min.js"></script>

<!-- Optional jQuery Library -->
<script src="/path/to/cdn/jquery.min.js"></script>

<!-- GSAP Marquee Plugin -->
<script src="/path/to/src/gsap-marquee.js"></script>

2. Set up your carousel with a wrapper element and inner container holding your items:

<div class="customMarquee" id="example">
  <div class="marqueeInner">
    <div class="marquee-item">Item 1</div>
    <div class="marquee-item">Item 2</div>
    <div class="marquee-item">Item 3</div>
    ... more Items here ...
  </div>
</div>

3. Initialize the carousel by creating a new gsapMarquee instance:

// jQuery
$('#example').gsapMarquee({
  // options here
});

// Vanilla JS
var myCarousel = gsapMarquee('#example', {
  // options here
});

4. If you have images in the carousel, always make sure they are fully loaded before you initialize the plugin. If you don't, the library will calculate widths based on unloaded images, leading to incorrect spacing. We recommend a JS library like imagesLoaded or a simple setTimeout after the window load event.

imagesLoaded('#example', function(){
  setTimeout(function(){
    gsapMarquee('#example', {
      // options here
    });
  }, 0);
});

5. Customize the carousel with the following options:

• speed (number, default: 100): Sets the animation speed in pixels per second.
• direction (string, default: 'ltr'): Determines the movement direction. Accepts 'ltr' for left-to-right or 'rtl' for right-to-left.
• pauseOnHover (boolean, default: true): Pauses the marquee animation when the mouse cursor enters the container.
• pauseOnClick (boolean, default: false): Toggles the animation's paused state each time the marquee is clicked.
• variableSpeed (boolean, default: false): When pauseOnHover is active, this option makes the marquee slow down on hover instead of stopping completely.
• startPaused (boolean, default: false): Initializes the marquee in a paused state, requiring a resume() call to start the animation.
• responsive (boolean, default: true): Automatically rebuilds the marquee's clones and recalculates widths on browser window resize events.
• loop (boolean, default: true): Enables continuous, endless looping. If set to false, the marquee will run through the items only once.
• containerSelector (string, default: '.customMarquee'): The CSS selector for the inner wrapper element that directly contains the marquee items.
• itemsSelector (string, default: '.marquee-item'): The CSS selector used to identify the individual items within the container.
• onComplete (function, default: null): A callback function that is triggered when a non-looping (loop: false) marquee finishes its single run. It receives the cycle count as an argument.

var myCarousel = gsapMarquee('#example', {
  speed: 100,
  direction: 'ltr', // ltr / rtl
  pauseOnHover: true,
  pauseOnClick: false,
  variableSpeed: false,
  startPaused: false,
  responsive: true,
  loop: true,
  containerSelector: '.customMarquee',
  itemsSelector: '.marquee-item',
  onComplete: null
});

6. API methods to control the carousel programmatically:

• myCarousel.pause(): Stop animation playback immediately.
• myCarousel.resume(): Resume paused animation from current position.
• myCarousel.isPaused(): Returns boolean indicating current pause state.
• myCarousel.rebuild(): Recalculate dimensions and clones after content changes.
• myCarousel.reverse(): Toggle direction between left-to-right and right-to-left.
• myCarousel.destroy(): Clean up event listeners and stop ticker for proper disposal.

7. For accessibility, it's a good practice to pause the animation when an interactive element inside receives focus.

myCarousel.items.forEach(function(el){
  el.addEventListener('focus', () => myCarousel.pause());
  el.addEventListener('blur', () => myCarousel.resume());
});

8. To respect user motion preferences:

if (window.matchMedia && window.matchMedia('(prefers-reduced-motion: reduce)').matches) {
  opts = opts || {};
  opts.startPaused = true;
}

9. Add CSS transforms for optimal animation performance:

.marqueeInner {
  will-change: transform;
}

10. If you have content loaded into the carousel dynamically, always rebuild the instance after layout stabilizes:

setTimeout(function(){
  myCarousel.rebuild();
}, 50);

FAQs:

Q: My marquee has a jump or gap when it loops. What's wrong?
A: This almost always happens when the library calculates item widths incorrectly. The most common cause is initializing the marquee before images have finished loading. Ensure all content, especially images and custom fonts, is fully loaded before you call gsapMarquee().

Q: Can I use this with React or Vue?
A: Yes. You can wrap it in a component. The key is to initialize the marquee in a useEffect (for React) or onMounted (for Vue) hook to ensure the DOM elements exist. Remember to use the destroy() method in the cleanup function of the hook to prevent memory leaks when the component unmounts.

Q: Why use this over a simple CSS animation?
A: Control and precision. GSAP's ticker provides smoother, more consistent timing than most CSS animations, especially under heavy CPU load. The JavaScript approach also allows for a rich API to pause, resume, reverse, and rebuild the marquee on the fly, which is very difficult to achieve with CSS alone.

Q: Can I use different speeds for multiple marquees on the same page?
A: Yes, each marquee instance maintains independent settings. You can initialize multiple marquees with different speeds, directions, and behaviors without conflicts.

Q: What happens if my content doesn't fill the viewport width?
A: The library automatically clones items until the total width exceeds the viewport width plus one item width. This ensures smooth looping regardless of original content length.

See Also:

• 10 Best Carousel Plugins In jQuery/JavaScript/CSS
• 10 Best Marquee-like Content Scrolling Plugins In JavaScript

---

This awesome jQuery plugin is developed by Rupashdas. For more Advanced Usages, please check the demo page or visit the official website.