Glass Gallery

v1.0.0

FreeGalleryScroll3DWebGLInteractiveTailwind

An immersive 3D glass-morphic photo gallery cube that disassembles into a flat responsive image collage on scroll.

Glass Gallery

Go fullscreen to customize props

Installation

npx vectorvesper add glass-gallery

Run npx vectorvesper init once first to set up your project.

Dependencies

npm install three @react-three/fiber @react-three/drei gsap @gsap/react

three
@react-three/fiber
@react-three/drei
gsap
@gsap/react

Also requires tailwindcss to be configured in your project.

Usage

Import

import { GlassGallery, GlassGalleryOverlay, Scene } from "@/components/vv/glass-gallery";

Usage

<GlassGallery />
<GlassGalleryOverlay />
<Scene />

Client-only component — disable SSR

This component uses WebGL and must be rendered client-side only.

import dynamic from "next/dynamic";

const GlassGallery = dynamic(
  () => import("@/components/vv/glass-gallery"),
  { ssr: false }
);

Tailwind CSS must be configured in your project for styles to apply correctly.

Props

A stunning 3D glass-morphic photo gallery built on React Three Fiber and GSAP. As you scroll, a glass cube/panel setup morphs, splits, and disintegrates into a flat 2D grid overlay. Fully interactive with mouse tilt and hover peek effects.

<GlassGallery />

The main WebGL gallery wrapper.

Prop	Type	Default	Description
`images`	`string[]`	`— (6 default stock photos)`	Array of image URLs. Minimum 6; auto-duplicated to fill all cube faces or grid panels.
`mode`	`"square" \| "rect" \| "quad"`	`"quad"`	Layout mode: 'square' (6 faces), 'rect' (12 panels), or 'quad' (24 tiles).
`cubeSize`	`number`	`0.5`	Base scale multiplier of the 3D cube/panels.
`autoSpinSpeed`	`number`	`0.15`	Idle rotation speed around the Y-axis when not scrolling.
`scrollSpins`	`number`	`1.0`	Number of full 360° revolutions during the scroll-down disintegration phase.
`mouseTiltIntensity`	`number`	`1.0`	Sensitivity multiplier for cursor-driven tilt rotation.
`backgroundColor`	`string`	`"#000000"`	Fallback background color of the canvas container.
`hoverTransparency`	`boolean`	`false`	Fades photos on hover in 3D mode to let users peek inside the hollow cube structure.
`photoOpacity`	`number`	`1.0`	Base opacity of individual photo panels (0.0 to 1.0).
`staticPreview`	`boolean`	`false`	Disables GSAP ScrollTrigger, mouse tracking, and scroll morphs. Ideal for static layouts.
`scroller`	`string \| Element`	`window`	Custom scroll container selector or DOM element to bind scroll animations to.
`lerpSpeed`	`number`	`0.12`	Interpolation speed for scroll progression smoothing.
`rotationLerpSpeed`	`number`	`0.08`	Rotation smoothing coefficient.
`scaleLerpSpeed`	`number`	`0.12`	Scale morphing interpolation speed.
`children`	`React.ReactNode`	`—`	DOM elements layered directly on top of the 3D canvas (ideal for overlay typography, titles).
`galleryItemWidth`	`number`	`—`	Override width of individual gallery items in the flat 2D grid layout.
`galleryItemHeight`	`number`	`—`	Override height of individual gallery items in the flat 2D grid layout.
`gridGapX`	`number`	`—`	Horizontal grid gap spacing in 2D layout.
`gridGapY`	`number`	`—`	Vertical grid gap spacing in 2D layout.
`className`	`string`	`—`	CSS class applied to the root wrapper container.
`style`	`React.CSSProperties`	`—`	Inline style overrides for the root wrapper container.

<GlassGalleryOverlay />

A luxury typography header panel optimized to slide overlay text on top of the 3D gallery.

Examples

Basic quad morph

<GlassGallery mode="quad" />

Simple 3D CubeUses 'square' mode with auto-spinning and transparency enabled.

<GlassGallery
  mode="square"
  cubeSize={0.65}
  autoSpinSpeed={0.3}
  hoverTransparency={true}
/>

With custom images & overlay

const list = [
  "/pic1.jpg", "/pic2.jpg", "/pic3.jpg",
  "/pic4.jpg", "/pic5.jpg", "/pic6.jpg"
];

<GlassGallery images={list}>
  <GlassGalleryOverlay />
</GlassGallery>

Client-only component. Relies on @react-three/fiber, Three.js, and GSAP ScrollTrigger. Must be imported dynamically with ssr: false to prevent Node.js render crashes.

Uses a single requestAnimationFrame loop managed by React Three Fiber. If embedding multiple instances, consider using the staticPreview flag to free up WebGL contexts.

Source

export { default } from "./GlassGallery";
export type { GlassGalleryProps } from "./GlassGallery";
export { default as GlassGalleryOverlay } from "./GlassGalleryOverlay";

View on GitHub →Report an issue