Docs·Image 2 Gif

Image 2 Gif

Frame-sequence player that turns a list of still images into a looping GIF-like animation.

Installation

$pnpm dlx shadcn@latest add @spiderui/image-2-gif

Usage

Cycles through a list of image URLs like a GIF — preload all frames, then advance on an interval. Supports custom renderers for next/image, one-shot playback, and loading placeholders.

API Reference

PropTypeDefault
imagesOrdered frame URLs to cycle through.
string[]—
intervalMilliseconds between frame advances.
number500
loopRestart from the first frame after the last.
booleantrue
onCompleteCalled once when loop is false and the last frame is reached.
() => void—
renderImageCustom frame renderer — e.g. next/image with fill.
(src: string, index: number) => ReactNode—
renderLoadingPlaceholder shown while frames preload.
() => ReactNode—
classNameClasses on the default img element or loading skeleton.
string—

Click on the icon in the top right of the example preview to view the source code for specific variants.

Keep in mind

This component is inspired by various open-source projects and patterns. Please verify licenses and implementation details before using in production.

Have any questions?
Contact on@ctrlcat0x
import { Image2Gif } from "@/components/ui/image-2-gif"
const frames = [
  "/frames/01.jpg",
  "/frames/02.jpg",
  "/frames/03.jpg",
]

export default function Page() {
  return (
    <div className="relative aspect-video w-full max-w-md">
      <Image2Gif images={frames} interval={200} className="size-full object-cover" />
    </div>
  )
}