Item Transition

// Code for item-transition/basic

Installation

Usage

import { ItemTransition } from "@/components/pluto-ui/item-transition"
import type { TransitionEffect } from "@/components/pluto-ui/item-transition"

const items = [
  { id: "1", image: "/assets/item-transitions/1.jpg", alt: "Image 1" },
  { id: "2", image: "/assets/item-transitions/2.jpg", alt: "Image 2" },
  { id: "3", image: "/assets/item-transitions/3.jpg", alt: "Image 3" },
]

function MyCarousel() {
  const [effect, setEffect] = useState<TransitionEffect>("cornerScale")

  return (
    <ItemTransition
      items={items}
      effect={effect}
      onEffectChange={setEffect}
      variant="small"
      showNavigation={true}
    />
  )
}

Props

Transition Effects

The component supports 17 different transition effects:

• cornerScale: Scales from corner with origin-based animation
• verticalScale: Vertical scaling with slide effect
• fall: Falling animation with scale transition
• forwardPulse: Forward pulse with depth effect
• rotatePulse: Rotating pulse animation
• heartbeat: Heartbeat-style scale animation
• coverflow: 3D coverflow-style rotation
• rotateSoftly: Gentle rotation transition
• deal: Card dealing animation
• ferris: Ferris wheel rotation effect
• shinkansen: Fast horizontal slide (like a bullet train)
• snake: Snake-like wavy movement
• shuffle: Shuffle with rotation
• photoBrowse: Photo browsing style transition
• slideBehind: Slide behind with scale effect
• vacuum: Vacuum suction effect
• hurl: Dramatic hurl with rotation
• slideForward: Slide forward with scale from corners (transparent variant)
• tableDrop: Table drop with rotation bounce (transparent variant)
• slideIt: Slide with rotation animation (transparent variant)
• bottleKick: Bottle kick with rotation and bounce (transparent variant)
• shelf: Off the shelf animation (transparent variant)

Variants

Small

The default variant, perfect for small image galleries:

// Code for item-transition/minimal

Transparent

Transparent variant for images with transparent backgrounds. This variant supports 5 specific effects optimized for transparent images:

// Code for item-transition/transparent

Examples

Basic Usage

// Code for item-transition/basic

Auto-play

Automatically advance through items:

// Code for item-transition/autoplay

Minimal

Simple carousel with minimal configuration:

// Code for item-transition/minimal

Type Definitions

export type TransitionEffect =
  | "cornerScale"
  | "verticalScale"
  | "fall"
  | "forwardPulse"
  | "rotatePulse"
  | "heartbeat"
  | "coverflow"
  | "rotateSoftly"
  | "deal"
  | "ferris"
  | "shinkansen"
  | "snake"
  | "shuffle"
  | "photoBrowse"
  | "slideBehind"
  | "vacuum"
  | "hurl"
  | "slideForward"
  | "tableDrop"
  | "slideIt"
  | "bottleKick"
  | "shelf"

export interface ItemTransitionItem {
  id: string
  image: string
  alt?: string
}

export interface ItemTransitionProps {
  items: ItemTransitionItem[]
  effect?: TransitionEffect
  onEffectChange?: (effect: TransitionEffect) => void
  variant?: "small" | "transparent"
  className?: string
  showNavigation?: boolean
  autoPlay?: boolean
  autoPlayInterval?: number
}

Features

• 22 Transition Effects: Choose from a wide variety of creative transitions (17 for small variant, 5 specific for transparent variant)
• Smooth Animations: Powered by framer-motion for fluid, performant animations
• Two Variants: Small and transparent variants for different use cases
• Auto-play Support: Optional automatic advancement through items
• Navigation Controls: Previous/next buttons with proper ARIA labels
• Type-safe: Full TypeScript support with exported types
• Theme-aware: Supports light and dark themes
• Responsive: Adapts to different screen sizes
• No CSS Files: All styling handled with Tailwind CSS

Customization

Custom Transition Effect

You can change the transition effect dynamically:

const [effect, setEffect] = useState<TransitionEffect>("cornerScale")

<ItemTransition
  items={items}
  effect={effect}
  onEffectChange={setEffect}
/>

Custom Styling

Override styles using Tailwind classes:

<ItemTransition
  items={items}
  className="rounded-lg shadow-xl"
  variant="small"
/>

Auto-play Configuration

Configure auto-play with custom interval:

<ItemTransition
  items={items}
  autoPlay={true}
  autoPlayInterval={5000} // 5 seconds
/>

Animation Details

All transitions use framer-motion's AnimatePresence with mode="wait" to ensure smooth transitions between items. Each effect has:

• Exit Animation: How the current item leaves
• Enter Animation: How the next item enters
• Direction Awareness: Different animations for next/previous navigation
• Timing: Consistent 0.4s base duration with customizable delays

Notes

• Requires motion (framer-motion) as a dependency
• Images should be optimized for web performance
• Navigation buttons are automatically positioned based on the variant
• The component prevents rapid clicking during animations
• Auto-play pauses when manually navigating

Credits

This component was inspired by the Item Transition Inspiration demo from Codrops, reimplemented with React and framer-motion.