circular-gallery

1"use client";
2 
3import * as React from "react";
4import { useEffect, useRef } from "react";
5import gsap from "gsap";
6import { cn } from "@/lib/utils";
7 
8/**
9 * Circular Gallery
10 *
11 * A relaxing 3D ring of images: many small cards are laid out around a giant
12 * tilted circle, the whole ring drifts with a gentle auto-rotation you can
13 * grab and spin, and the cursor parallaxes the tilt. Hovering a card lifts it
14 * and mirrors it in a large centre preview.
15 *
16 * Ported from the vanilla "CodeGrid 3D Circular Image Gallery" (GSAP) into a
17 * single, self-contained, prop-driven React component. The original's full-page
18 * ScrollTrigger is replaced with drag + auto-rotation so it works inside any
19 * container. GSAP is the only runtime dependency.
20 */
21 
22export interface CircularGalleryProps {
23  /** Image URLs, cycled around the ring. When omitted, neutral placeholder cards are shown. */
24  images?: string[];
25  /** Number of cards in the ring. Defaults to 150. */
26  count?: number;
27  /** Base tilt of the ring in degrees (rotateX). Defaults to 55. */
28  tilt?: number;
29  /** Ring radius in px (card distance from centre). Defaults to 400. */
30  radius?: number;
31  /** Card width in px. Defaults to 45. */
32  itemWidth?: number;
33  /** Card height in px. Defaults to 60. */
34  itemHeight?: number;
35  /** Slowly spin the ring on its own. Defaults to true. */
36  autoRotate?: boolean;
37  /** Auto-rotation speed in degrees per second. Defaults to 4. */
38  autoRotateSpeed?: number;
39  /** Show the large centre preview that follows the hovered card. Defaults to true. */
40  showPreview?: boolean;
41  /** Parallax the ring's tilt toward the cursor. Defaults to true. */
42  parallax?: boolean;
43  /** Extra classes for the root element. */
44  className?: string;
45}
46 
47export function CircularGallery({
48  images,
49  count = 150,
50  tilt = 55,
51  radius = 400,
52  itemWidth = 45,
53  itemHeight = 60,
54  autoRotate = true,
55  autoRotateSpeed = 3,
56  showPreview = true,
57  parallax = true,
58  className,
59}: CircularGalleryProps) {
60  const rootRef = useRef<HTMLDivElement>(null);
61  const galleryRef = useRef<HTMLDivElement>(null);
62  const previewRef = useRef<HTMLImageElement>(null);
63  const previewWrapRef = useRef<HTMLDivElement>(null);
64 
65  const srcOf = (i: number) =>
66    images && images.length > 0 ? images[i % images.length] : undefined;
67  const defaultPreview = srcOf(0);
68 
69  // Live-tunable knobs read inside the ticker/handlers without rebuilding.
70  const optsRef = useRef({ autoRotate, autoRotateSpeed, parallax, tilt });
71// … truncated