Orbital Image Wheel

Installation

File Structure

Usage

import { OrbitalImageWheel } from "@/components/unlumen-ui/orbital-image-wheel";

const images = [
  {
    src: "/photos/01.jpg",
    alt: "Capsule pack",
    label: "Capsule",
    subtitle: "Precision delivery",
  },
  {
    src: "/photos/02.jpg",
    alt: "Lab interior",
    label: "Lab",
    subtitle: "AI diagnostics",
  },
  {
    src: "/photos/03.jpg",
    alt: "Clinical scan",
    label: "Vision",
    subtitle: "Predictive screening",
  },
];

export default function Example() {
  return <OrbitalImageWheel images={images} />;
}

With custom subtitle animation controls

<OrbitalImageWheel
  images={images}
  subtitleDirection="bottom"
  subtitleSpeed={1.25}
  subtitleStagger={0.014}
/>

With a custom scroll container

If your layout scrolls inside a container (overflow-y-auto) instead of the viewport, pass scrollContainerRef so GSAP ScrollTrigger uses the correct scroller.

"use client";

import { useRef } from "react";
import { OrbitalImageWheel } from "@/components/unlumen-ui/orbital-image-wheel";

export default function ScrollContainerExample() {
  const scrollRef = useRef<HTMLDivElement>(null);

  return (
    <div ref={scrollRef} className="h-[80vh] overflow-y-auto">
      <OrbitalImageWheel images={images} scrollContainerRef={scrollRef} />
    </div>
  );
}

Tuning wheel geometry and pacing

<OrbitalImageWheel
  images={images}
  turns={2.4}
  wheelSize={1800}
  cropRatio={0.7}
  itemWidth={260}
  itemHeight={340}
  scrollLength={360}
  focusSpread={0.28}
  scrollSensitivity={0.62}
/>

API Reference

How it works

The component combines GSAP ScrollTrigger and geometric transforms to simulate a cinematic wheel:

1. A large circular layout is positioned below the viewport, so only its top arc is visible.
2. Scroll progress rotates virtual card angles around the circle.
3. Each card receives position, depth, tilt, blur, brightness, saturation, and scale based on its angular distance from the top focus anchor.
4. The active index is stabilized with hysteresis to reduce jitter around boundaries.
5. The caption updates from the active item and keeps the title pill centered with dynamic edge spacers.

Caption behavior

• Subtitle source: image.subtitle -> image.alt -> "Visual Story"
• Title source: image.label -> image.alt -> fallback "Image N"
• Subtitle animation is delegated to MotionSubtitle via registry dependency (@unlumen-ui/motion-subtitle).

Tuning guide

• Slower wheel motion: increase scrollLength and/or decrease scrollSensitivity.
• Stronger foreground/background separation: increase blur, darknessStrength, saturationStrength, or brightnessBoost.
• Softer effect: reduce blur, raise dim, and reduce scaleEffect.
• More centered focus window: lower focusSpread for tighter spotlight, raise for broader spotlight.
• More/less visible wheel arc: lower cropRatio to show more of the wheel, raise it to hide more below the fold.

Notes

• The wheel center is anchored below the viewport so only its upper arc is visible.
• Clicking a title pill animates scroll to the corresponding image position.
• Captions are derived from the active image with built-in fallbacks.
• Uses GSAP ScrollTrigger for wheel motion and Motion for subtitle text animation.
• Works with viewport scroll and with custom scrollers through scrollContainerRef.

Credits

Built by leo.