High-performance React marquee powered by GSAP
Horizontal and vertical marquees, fill mode, drag, scroll-follow, and GSAP-powered animation with TypeScript support.
Everything you need
A comprehensive set of features to build the perfect auto-scrolling marquee for any use case.
Smaller where it matters
GSAP core stays in the initial graph. Observer and Draggable now load only when their features are enabled.
| Metric | v0.3.2 | v0.4.0 | Change |
|---|---|---|---|
| Default bundle (gzip) | 57.4 kB | 33.2 kB | −42.2% |
| Interactive bundle (gzip) | 57.4 kB | 50.0 kB | −12.8% |
| Observed package build | 27.8 s | 4.7 s | −83.1% |
Equivalent React rerenders no longer rebuild timelines or listeners. Reduced-motion mode creates no clones or animation resources. Build time is one same-machine observation, not a statistical benchmark. npm tarball grows from 9.6 kB to 17.6 kB because v0.4.0 includes more runtime guards, types, and documentation.
Interactive Examples
Check out some of the common use cases and configurations.
<Marquee dir="left" speed={50}>
<div className="...">Scrolling text goes here</div>
</Marquee>API Playground
Experiment with animation and interaction properties, then copy the generated code.
<Marquee
dir="left"
loop={-1}
paused={false}
respectReducedMotion={true}
delay={0}
speed={250}
fill={false}
maxDuplicates={100}
pauseOnHover={false}
gradient={true}
gradientColor="#000000"
spacing={32}
draggable={false}
scrollFollow={false}
scrollSpeed={2.5}
>
<div className="text-4xl md:text-6xl font-black text-primary uppercase whitespace-nowrap px-8">
GSAP REACT MARQUEE
</div>
</Marquee>API Reference
A complete list of props for gsap-react-marquee v0.4.0.
| Prop | Type | Default | Description |
|---|---|---|---|
| children | ReactNode | Required | Content rendered inside each marquee item |
| className | string | undefined | Class applied to each .gsap-react-marquee-content element |
| containerClassName | string | undefined | Class applied only to the root viewport |
| containerStyle | CSSProperties | undefined | Inline styles applied to the root viewport |
| containerProps | HTML div attributes | undefined | ARIA, data attributes, and event handlers applied to the root viewport |
| dir | "left" | "right" | "up" | "down" | "left" | Direction of movement |
| loop | number | -1 | Number of timeline repeats (-1 = infinite) |
| paused | boolean | false | Controls whether the current timeline is paused |
| respectReducedMotion | boolean | true | Renders one static original when reduced motion is requested |
| delay | number | 0 | Delay before the animation starts (in seconds) |
| speed | number | 100 | Speed of the marquee animation in px/s |
| fill | boolean | false | Repeats content enough times to cover the measured marquee area |
| maxDuplicates | number | 100 | Maximum additional clones in fill mode, capped internally at 250 |
| pauseOnHover | boolean | false | Pauses on pointer hover and resumes on leave |
| gradient | boolean | false | Enables edge gradient overlays |
| gradientColor | string | undefined | Explicit gradient color. Overrides automatic background detection |
| spacing | number | 16 | Gap between marquee items, in pixels |
| draggable | boolean | false | Enable dragging to scroll manually |
| scrollFollow | boolean | false | Adjusts timeline speed from wheel/scroll direction |
| scrollSpeed | number | 2.5 | Scroll-follow multiplier. Clamped between 1.1 and 4 |
The component also forwards a ref to the root HTMLDivElement. Numeric values are normalized before reaching layout or GSAP; invalid values use documented finite defaults.
Advanced Under the Hood
Intelligent Detection
The component measures the active root and content axes, waits for finite positive geometry, and ignores clone-generated resize loops. Fill mode uses a configurable duplicate limit of 100 with an internal safety ceiling of 250.
Orientation-Aware
GSAP React Marquee naturally adapts its animation rules depending on direction. left/right uses xPercent optimizations whereas up/down binds securely to yPercent with flex column structures. Gradient overlays position themselves perfectly based on the flow.
Runtime Ready
The package injects its base CSS from the bundled entrypoint, forwards refs to the root container, and re-measures after resize or image load events. In Next.js, import and render it from a client component because it uses DOM measurement and layout effects.
Recent Changelog
v0.4.0
Latest: Stable measurement, finite/reverse loops, pause, drag, scroll, and resize behavior
Accessible SSR clones, focus isolation, and reduced-motion static rendering
New containerClassName, containerStyle, containerProps, maxDuplicates, and respectReducedMotion APIs
Lazy Observer/Draggable loading and equivalent-rerender resource reuse
Verified with React 18/19, GSAP 3.12/3.13, Node.js 20/22, Chromium, and WebKit
v0.3.2
Peer dependencies are explicit: gsap and @gsap/react
Runtime notes for Next.js client components
Forwarded ref documented for the root container
Updated sizing, styling, and troubleshooting docs
v0.3.0
🎨 BREAKING: Removed alignVertical prop. Vertical uses native flex.
✨ Added proper Y-axis animations (up/down)
🎨 Smart gradient overlays adapt to orientation
🔧 Refactored animation engine for X & Y
v0.2.4
✨ Intelligent container detection
🚀 Enhanced duplicate calculation algorithm
🔧 Smarter target width looping logic
🛡️ Added max limit to prevent perf issues