Collection Surfer

A 3D scroll-driven collection viewer where items surf along a perspective track. Perfect for immersive showcases.

Installation

pnpm dlx shadcn@latest add @componentry/collection-surfer

Dependencies: framer-motion clsx tailwind-merge

Usage

API Reference

Prop	Type	Default
`items`	`CollectionItem[]` Array of items to display. Each item must have id (number), image (string URL), and title (string).	—
`variant`	`"magnetic" \| "uplift" \| "simple"` Visual interaction style. 'magnetic' scales cards on hover, 'uplift' moves cards vertically, 'simple' has no hover effects.	`"magnetic"`

Working with this component

Prepare the collection

Provide a non-empty items array. Each entry has a numeric id, an image URL, and a title. The source duplicates the items to keep the visual sequence looping.

Give the scene its own page

Collection Surfer uses a fixed viewport scene and a 50,000px scroll spacer. It is designed as a page-level experience; use a dedicated route or iframe when embedding it into documentation.

Choose the pointer behavior

The simple variant skips the mouse-position updates used by the interactive variants. Review the source and test the chosen variant on touch devices before using it as the only way to browse important content.

Keep in mind

This component is inspired by various open-source projects and patterns. Please verify licenses and implementation details before using in production.

Need a custom component?

I build bespoke UI components & websites tailored to your brand.

DM me on X