Scroll Gallery

Installation

npx shadcn@latest add @soralabs/scroll-gallery

Usage

Basic

import { ScrollGallery } from "@/components/sora-ui/blocks/scroll-gallery";

const slides = [
  { title: "Room 14B", image: "/images/slide-1.jpg", url: "/project/1" },
  {
    title: "Subject Identified",
    image: "/images/slide-2.jpg",
    url: "/project/2",
  },
];

export default function Page() {
  return <ScrollGallery slides={slides} />;
}

Editorial preset (variant="studio")

Full-bleed hero with a three-column info band (prefix, title, link) and large white type:

<ScrollGallery slides={slides} variant="studio" />

variant="minimal" (default) ships structural layout only — add your own typography via the classNames prop.

Custom class map (advanced)

Import SCROLL_GALLERY_STUDIO_CLASSES to extend or partially override the studio preset:

import {
  SCROLL_GALLERY_STUDIO_CLASSES as studio,
  ScrollGallery,
} from "@/components/sora-ui/blocks/scroll-gallery";

<ScrollGallery
  variant="studio"
  classNames={{ titleText: cn(studio.titleText, "text-amber-200") }}
  slides={slides}
/>;

Custom labels & timing

<ScrollGallery
  slides={slides}
  prefixLabel="Projects"
  linkLabel="View case study"
  showPrefix={false}
  scrollPerTransition={800}
  timing={{
    titleChangeThreshold: 0.25,
    scaleFrom: 1.15,
    stripRevealSpeed: 2.5,
  }}
/>

Place ScrollGallery at the root scroll level of the page. GSAP pin requires the section to scroll within window — it will not work correctly inside a custom scroll container unless you pass scroller.

Use high-quality full-bleed images (at least 1920 × 1080). The component crops to object-fit: cover so landscape images work best.

Props

ScrollGallerySlide

ScrollGalleryTiming

When to Use

Use ScrollGallery for creative agency home pages, portfolio showcases, or editorial sections where each project or item deserves a dedicated full-screen moment. The pinned scroll pattern forces a deliberate, focused presentation — the user can only advance by scrolling, which creates a chapter-by-chapter rhythm.

Provide at least 3 slides for the scroll distance to feel earned. With fewer than 3, the section feels short and the pin may disorient users.

Accessibility

The title element stays in the DOM for screen readers while GSAP animates it. Images use accessible alt text from the slide title, and the CTA link remains keyboard-focusable and updates href and linkLabel on each slide transition.