@advpanda/gsap-orbit-carousel

A GSAP-powered React carousel with animated curved orbit paths.

What the package does: handles the animation only — the curved SVG paths, GSAP motion along them, crossfade between slides, orbit circle flow, and auto-play timer.

What the user provides: everything visual — main product images, orbit circle images, orbit labels, title text, background colors, and where to place the component.

Installation

npm install @advpanda/gsap-orbit-carousel gsap

Peer dependencies: react >=17, react-dom >=17, gsap >=3.11

Important Note : Only for 5 slides.

User Side Setup

1. Define your slides

Every piece of content comes from you — images, labels, titles, colors.

import type { CarouselSlide } from "@advpanda/gsap-orbit-carousel";

const slides: CarouselSlide[] = [
  {
    id: "product-1",

    // Main big image shown in the centre
    image: "/your-images/product-1.webp",

    // Title shown in the bottom bar
    title: "Your Product Name",

    // Small circular image + label on the LEFT orbit curve
    leftOrbitItems: [
      {
        image: "/your-images/ingredient-1.webp",
        label: "Ingredient One",
      },
    ],

    // Small circular image + label on the RIGHT orbit curve
    rightOrbitItems: [
      {
        image: "/your-images/ingredient-2.webp",
        label: "Ingredient Two",
      },
    ],
  },

  {
    id: "product-2",
    image: "/your-images/product-2.webp",
    title: "Second Product Name",
    leftOrbitItems:  [{ image: "/your-images/ing-3.webp", label: "Ingredient Three" }],
    rightOrbitItems: [{ image: "/your-images/ing-4.webp", label: "Ingredient Four"  }],
  },

  {
    id: "product-3",
    image: "/your-images/product-3.webp",
    title: "Third Product Name",
    leftOrbitItems:  [{ image: "/your-images/ing-5.webp", label: "Ingredient Five" }],
    rightOrbitItems: [{ image: "/your-images/ing-6.webp", label: "Ingredient Six"  }],
  },
];

2. Drop it anywhere in your layout

import { OrbitCarousel } from "@advpanda/gsap-orbit-carousel";

export default function YourSection() {
  return (
    <OrbitCarousel
      slides={slides}
      autoPlayInterval={5000}      // ms between slides, 0 = disabled
    />
  );
}

That's it. The carousel renders full-screen (100vh) by default. Place it inside any section or page.

All Props

| Prop | Type | Required | Description | |---|---|---|---| | slides | CarouselSlide[] | ✅ | Your slide data — all images, labels, titles | | autoPlayInterval | number | ✅ | Auto-advance ms. 0 to disable | | showTitle | boolean | — | Show/hide the top-left title. Default true | | showOrbits | boolean | — | Show/hide the side orbit paths. Default true | | showDots | boolean | — | Show/hide dot indicators. Default true | | showArrows | boolean | — | Show/hide prev/next arrows. Default true | | renderImage | (slide, index) => ReactNode | — | Custom image renderer | | renderTitle | (slide) => ReactNode | — | Custom bottom bar content | | onSlideChange | (index, slide) => void | — | Fires on every slide change | | className | string | — | Extra class on the root element | | style | CSSProperties | — | Inline styles on the root element |

CarouselSlide Type

interface CarouselSlide {
  id: string;                    // unique key for each slide
  image: string;                 // your main product image URL
  title: string;                 // your product title
  leftOrbitItems: OrbitItem[];   // your left orbit circle
  rightOrbitItems: OrbitItem[];  // your right orbit circle
}

interface OrbitItem {
  image: string;   // your small circular thumbnail URL
  label: string;   // your label text beside the circle
}

Advanced Usage

Using Next.js <Image>

If you're on Next.js use renderImage to swap in the <Image> component:

import Image from "next/image";
import { OrbitCarousel } from "@advpanda/gsap-orbit-carousel";

export default function YourSection() {
  return (
    <OrbitCarousel
      slides={slides}
      autoPlayInterval={5000}
      renderImage={(slide) => (
        <Image
          src={slide.image}
          alt={slide.title}
          fill
          className="object-contain"
          priority
        />
      )}
    />
  );
}

Custom bottom bar

Use renderTitle to replace the default title pill with anything you want:

<OrbitCarousel
  slides={slides}
  autoPlayInterval={5000}
  renderTitle={(slide) => (
    <div style={{ display: "flex", flexDirection: "column", alignItems: "center" }}>
      <span style={{ color: "white", fontSize: "1.3rem" }}>{slide.title}</span>
      <span style={{ color: "rgba(255,255,255,0.6)", fontSize: "0.8rem" }}>Shop Now →</span>
    </div>
  )}
/>

Listening to slide changes

<OrbitCarousel
  slides={slides}
  autoPlayInterval={5000}
  onSlideChange={(index, slide) => {
    console.log("Active:", index, slide.title);
  }}
/>

Disable auto-play

<OrbitCarousel
  slides={slides}
  autoPlayInterval={0}
/>

Hide parts of the UI

<OrbitCarousel
  slides={slides}
  autoPlayInterval={5000}
  showTitle={false}    // hide top-left title
  showOrbits={false}   // hide the side orbit paths
  showDots={false}     // hide dot indicators
  showArrows={false}   // hide prev/next arrows
/>

What the Package Does vs What You Provide

| | Package | You | |---|---|---| | Curved SVG orbit paths | ✅ | | | GSAP motion animation | ✅ | | | Crossfade between slides | ✅ | | | Orbit circle flow effect | ✅ | | | Teleport trick (no jump glitch) | ✅ | | | Auto-play timer | ✅ | | | Main product images | | ✅ | | Orbit circle images | | ✅ | | Orbit labels / text | | ✅ | | Product titles | | ✅ | | Background colors | | ✅ | | Where to place it | | ✅ |

Notes

• No CSS file or Tailwind required — fully inline styles.
• Works with Next.js App Router, Vite, CRA, or any React setup.
• GSAP MotionPathPlugin is registered automatically — you don't need to do anything.
• Add only 5 slides.