aurora-carousel

Beautiful React carousel & gallery components with cinematic animations powered by GSAP.

6 unique layouts — none of the boring horizontal sliders.

Installation

# npm
npm install aurora-carousel gsap

# yarn
yarn add aurora-carousel gsap

# pnpm
pnpm add aurora-carousel gsap

GSAP is a peer dependency — you must install it alongside aurora-carousel.

Requirements

| Peer dependency | Version | |---|---| | react | ≥ 18 | | react-dom | ≥ 18 | | gsap | ≥ 3 |

Next.js App Router

All components include 'use client' and are fully compatible with the Next.js App Router.
Import them normally in any Client Component or in a Server Component file — Next.js will handle the boundary automatically.

// app/gallery/page.tsx  — no 'use client' needed here
import { Coverflow } from 'aurora-carousel'

const items = [
  { id: 1, src: '/images/photo1.jpg', alt: 'Photo 1', caption: 'Sunset' },
  { id: 2, src: '/images/photo2.jpg', alt: 'Photo 2', caption: 'Mountains' },
]

export default function GalleryPage() {
  return <Coverflow items={items} />
}

Data format

Every component accepts an items array of CarouselItem objects:

import type { CarouselItem } from 'aurora-carousel'

const items: CarouselItem[] = [
  {
    id: 1,               // string | number — required, must be unique
    src: '/img/1.jpg',   // string — required, image URL or path
    alt: 'Photo 1',      // string — optional, alt text
    caption: 'Sunset',   // string — optional, overlay text
  },
]

Components

Coverflow

3D Apple Music-style carousel with perspective and rotateY transforms. Supports drag/swipe.

import { Coverflow } from 'aurora-carousel'

<Coverflow
  items={items}
  perspective={1000}   // px — camera distance, default 1000
  autoPlay={false}     // boolean, default false
  interval={3000}      // ms between auto slides, default 3000
  className="my-cf"    // extra CSS class on the container
/>

Navigation: click a side card, use the arrow buttons, drag horizontally, or enable autoPlay.

StackCards

A physical pile of cards. Drag the top card away to reveal the next one, or click the Skip button.

import { StackCards } from 'aurora-carousel'

<StackCards
  items={items}
  stackOffset={8}    // px vertical offset between stacked cards, default 8
  autoPlay={false}
  interval={3000}
  className="my-sc"
/>

Interaction: drag the top card in any direction (threshold 80 px) to dismiss it. The pile reorders with a smooth GSAP animation.

OrbitCarousel

Images arranged in a 3D ring that rotates in space like a planet's orbit.

import { OrbitCarousel } from 'aurora-carousel'

<OrbitCarousel
  items={items}
  radius={320}    // px — ring radius, default 320
  tilt={10}       // deg — ring tilt on X axis, default 10
  autoPlay={false}
  interval={3000}
  className="my-oc"
/>

Navigation: arrow buttons, dot indicators, or drag horizontally.

MasonryGrid

A Pinterest-style masonry grid with a staggered GSAP entrance animation. Clicking any image opens a lightbox.

import { MasonryGrid } from 'aurora-carousel'

<MasonryGrid
  items={items}
  columns={3}              // number of columns, default 3
  gap={16}                 // px gap between items, default 16
  scrollTrigger={false}    // animate on scroll instead of on mount, default false
  className="my-mg"
/>

When scrollTrigger={true}, gsap/ScrollTrigger is imported dynamically to avoid SSR issues.

FullscreenSlider

Opens a fullscreen overlay with configurable cinematic transitions. Shows a thumbnail strip to open specific slides.

import { FullscreenSlider } from 'aurora-carousel'

<FullscreenSlider
  items={items}
  transition="parallax"   // 'fade' | 'zoom' | 'parallax', default 'fade'
  autoPlay={false}
  interval={4000}
  className="my-fs"
/>

| Transition | Effect | |---|---| | fade | Crossfade between slides | | zoom | Incoming slide scales from 1.12 → 1 | | parallax | Outgoing slides left, incoming from right at different depths |

Interaction: click any thumbnail to open the overlay. Use arrows, drag, or press close (✕).

ScatteredGallery

Photos appear scattered randomly across the container. On hover (or click), they animate into an ordered grid — then back on leave (or second click).

import { ScatteredGallery } from 'aurora-carousel'

<ScatteredGallery
  items={items}
  triggerOn="hover"    // 'hover' | 'click', default 'hover'
  className="my-sg"
/>

The scatter positions are calculated with a deterministic seed (based on index) — no Math.random() during render, so there are no SSR hydration mismatches.

TypeScript

All props interfaces are exported:

import type {
  CarouselItem,
  BaseCarouselProps,
  CoverflowProps,
  StackCardsProps,
  OrbitCarouselProps,
  MasonryGridProps,
  FullscreenSliderProps,
  ScatteredGalleryProps,
} from 'aurora-carousel'

Styling & Theming

aurora-carousel ships with plain CSS using prefixed class names (aurora-cf-*, aurora-sc-*, etc.), injected automatically when the component is imported — no manual CSS import required.

Customising styles

Override any class in your own stylesheet:

/* Override Coverflow card size */
.aurora-cf-card {
  width: 320px;
  height: 400px;
}

/* Change dot colour in Orbit */
.aurora-oc-dot--active {
  background: hotpink;
  opacity: 1;
}

Dark / light theme

All components inherit color from their parent for text elements (dots, buttons). Set color on a wrapper to theme them:

.dark-theme {
  color: #ffffff;
  background: #0a0a0a;
}

Complete example

'use client'

import {
  Coverflow,
  StackCards,
  OrbitCarousel,
  MasonryGrid,
  FullscreenSlider,
  ScatteredGallery,
} from 'aurora-carousel'
import type { CarouselItem } from 'aurora-carousel'

const photos: CarouselItem[] = [
  { id: 1, src: 'https://picsum.photos/seed/p1/800/600', alt: 'Photo 1', caption: 'Alpine Lake' },
  { id: 2, src: 'https://picsum.photos/seed/p2/800/600', alt: 'Photo 2', caption: 'Desert Dunes' },
  { id: 3, src: 'https://picsum.photos/seed/p3/800/600', alt: 'Photo 3', caption: 'City Lights' },
  { id: 4, src: 'https://picsum.photos/seed/p4/800/600', alt: 'Photo 4', caption: 'Ocean Sunset' },
  { id: 5, src: 'https://picsum.photos/seed/p5/800/600', alt: 'Photo 5', caption: 'Forest Path' },
]

export default function Gallery() {
  return (
    <div style={{ padding: 40, display: 'flex', flexDirection: 'column', gap: 80 }}>

      <Coverflow items={photos} perspective={900} />

      <StackCards items={photos} stackOffset={10} />

      <OrbitCarousel items={photos} radius={300} tilt={12} />

      <MasonryGrid items={photos} columns={3} gap={12} scrollTrigger />

      <FullscreenSlider items={photos} transition="zoom" />

      <ScatteredGallery items={photos} triggerOn="click" />

    </div>
  )
}

License

MIT © aurora-carousel contributors