next-marquee
v1.0.0
Published
Compositor-driven React marquee built on the Web Animations API. Jank-free runtime speed changes, reverse scrolling, phase-preserving resize, reduced-motion support. SSR-safe, works with Next.js App Router and Pages Router.
Maintainers
Readme
next-marquee
A compositor-driven React marquee built on the Web Animations API. Framework-agnostic — works in any React 18+ app, with first-class support for Next.js (App Router and Pages Router, SSR-safe) and Typescript.
DEMO
Why another marquee?
Most marquee components animate with requestAnimationFrame + per-frame style mutation, which forces style recalculation and re-layerization on the main thread every frame. This one drives a single WAAPI transform animation that runs entirely on the compositor thread — after setup, the main thread does zero work per frame.
- Jank-free runtime speed changes. Speed is applied via
updatePlaybackRate()on a fixed timeline, so changingspeedmid-scroll never causes a position jump. Wire it to press-and-hold fast-forward buttons freely. - Reverse scrolling. Negative
speedplays the marquee backwards, with automatic runway management so backward playback never hits the animation's start and stalls. - Seamless looping. The loop distance is measured with sub-pixel precision and includes margins on the content set and
gapon the track, so the wrap from one pass to the next is invisible at any content width. - Position-preserving resize. When content or container size changes (late-loading fonts or images, responsive breakpoints, live data), the marquee continues from the exact pixel position it was at — no snap back to the start, no jump.
- Reduced motion. Respects
prefers-reduced-motion: reduceautomatically, including live changes to the preference. - No styling dependency. No CSS import, no Tailwind requirement. Layout is inline; hooks for your own classes are provided.
Install
npm install next-marqueeyarn add next-marqueeTypeScript types are bundled — no separate @types package needed.
Usage
import Marquee from "next-marquee"
export default function Ticker() {
return (
<Marquee speed={80} pauseOnHover>
<span>Breaking news item one</span>
<span>Breaking news item two</span>
</Marquee>
)
}Even spacing between items, including between the last item of one set and the first item of the next — use the same gap inside each set (className) and between sets (loopClassName):
<Marquee className="gap-8" loopClassName="gap-8">
{items}
</Marquee>Press-and-hold scrub buttons:
<Marquee speed={isBackwarding ? -800 : isForwarding ? 800 : 60}>
{items}
</Marquee>Props
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| children | ReactNode | — | Content of one marquee set. Duplicated internally to fill the container. |
| speed | number | 60 | Pixels per second. Negative values scroll backwards. Changing it at runtime is seamless. |
| play | boolean | true | Pauses/resumes the animation, preserving position. |
| pauseOnHover | boolean | true | Pause while the pointer is over the marquee. |
| loop | number | Infinity | Number of passes (one pass = one content-set width plus its horizontal margins and the track's gap). When finite, the marquee stops at the end and onComplete fires. |
| onComplete | () => void | — | Called when a finite loop finishes. |
| rootClassName | string | — | Class for the outer clipping container. |
| loopClassName | string | — | Class for the moving track. A gap here sets the spacing between content sets. |
| className | string | — | Class for each content set. Horizontal margins are included in the loop distance. |
Known limitations
- Combining a finite
loopwith negativespeedis unsupported: playing backwards to time zero ends the animation.onCompleteis guarded against firing in that case, but the marquee will stop. - If your forward/backward controls are rendered inside the marquee,
pauseOnHoverwill pause the animation while they're hovered. Place controls outside the component, or disablepauseOnHoverwhile a control is pressed. - Duplicated content sets are
aria-hidden; interactive elements insidechildrenwill appear multiple times in the DOM but only the first set is exposed to assistive technology.
Browser support
Requires Element.animate, Animation.updatePlaybackRate, and ResizeObserver — available in all evergreen browsers. No IE11.
License
MIT
