horizontal-scroll-gallery

Installation
SKILL.md

Horizontal Scroll Gallery

When to use this

  • You want a vertical-scroll-drives-horizontal-translate section (scroll down, content visually slides left), the pattern used for image galleries embedded inside an otherwise vertical page.
  • You want a genuinely horizontally-scrollable track (trackpad two-finger horizontal swipe, touch swipe, scrollbar) with clean snap points between items: use native CSS scroll-snap, not JS.
  • You need drag-to-scroll (mouse-drag or touch-drag directly on the track) with momentum/inertia after release, common for image carousels and portfolio pieces.
  • Do NOT use this for a single full-bleed image carousel with just next/prev buttons and no scroll-linked motion; that's simpler slider UI, not a scroll-driven gallery, and adding scroll-hijacking machinery there is overkill.

Mental model

There are three fundamentally different input models here and picking the wrong one is the most common mistake in this pattern.

Vertical-drives-horizontal (pin + translate): the section is pinned (see sticky-pinning-sequences) while vertical scroll progress is mapped to a horizontal translateX on an inner track. This is scroll-hijacking in the literal sense: the user's vertical scroll gesture produces horizontal visual movement. It works well for showcase sections embedded in a narrative page, but it fundamentally overrides the user's actual input axis, so it must be done carefully (correct total scroll distance, working keyboard nav, disabled on touch where it fights native swipe expectations).

Native horizontal scroll-snap: the track is a real overflow-x: auto scroller, and scroll-snap-type/scroll-snap-align ask the browser to settle on item boundaries after a scroll gesture ends. This respects the user's actual input axis (a real two-finger horizontal trackpad swipe or a touch swipe scrolls it, nothing is hijacked), keeps native scrollbar/keyboard-arrow support, and costs zero JS for the mechanics. This is the correct default when the gallery is a standalone unit, not nested inside a page-length vertical narrative.

Drag-to-scroll with momentum: for input devices without a natural horizontal gesture over the element (mouse users without a horizontal wheel), you add a pointerdown/pointermove/pointerup drag handler that directly manipulates scrollLeft, then on release applies a decaying velocity to simulate momentum, since a mouse drag-release with no momentum feels dead compared to what users expect from touch/trackpad interactions.

The critical UX problem all three variants share: horizontal scroll is not discoverable. A user looking at a normal vertical page has no built-in expectation that a specific section scrolls sideways. Every implementation needs an explicit edge affordance (partial next-item visible at the edge, a drag cursor icon, a fade gradient, arrow buttons) or most users will simply never discover the content past the first screen.

Installs
2
First Seen
Aug 30, 2026
horizontal-scroll-gallery — avnehsbhatia/ultraui