Image Ring

An editorial orbit of framed plates - drag for inertia, snap to the nearest face, step with keys or dots. Depth fade, focus scale, and a light HUD ship on by default. Built with motion.

Default

Drag to orbit, click dots or use arrow keys to step. Front face lifts; sides fall away with depth.

Loading…

Installation

CLI

npx @sonojs/ui@latest add image-ring

Also needsnpm i motion

Usage

page.tsx

"use client"

import { ImageRing } from "@/components/3d/image-ring"

export default function Page() {
  return (
    <div className="h-[560px] w-full">
      <ImageRing
        captions={["Midnight market", "Glass canyon", "Quiet harbour"]}
        autoPlayMs={4200}
      />
    </div>
  )
}

Props

Prop	Type	Default	Description
images	string[]	bundled ./images	Image URLs around the ring. Defaults to the shipped `images/` files next to the component.
captions	string[]	-	Optional labels aligned with `images` for the HUD.
width	number	280	Face width in pixels. Height follows `aspectRatio`.
aspectRatio	number	0.75	Width ÷ height of each plate (default 3/4).
perspective	number	1800	CSS perspective distance.
imageDistance	number	460	Distance of each face from the ring center.
depthFade	number	0.78	Opacity floor for the farthest faces.
focusScale	number	1.04	Scale lift applied to the front face.
showHud	boolean	true	Index strip + caption under the stage.
showDots	boolean	true	Snap dots for direct face selection.
autoPlayMs	number	0	Idle advance interval in ms. `0` disables.
draggable	boolean	true	Enable drag and inertia spin.
onIndexChange	(index: number) => void	-	Called when the front face index changes.
initialRotation	number	180	Starting rotateY in degrees.
animationDuration	number	1.15	Entrance duration in seconds.
staggerDelay	number	0.07	Delay between face entrances.
mobileBreakpoint	number	768	Viewport width that triggers mobile scale.
mobileScaleFactor	number	0.82	Scale applied on small viewports.
inertiaPower	number	0.85	Inertia power after release.
inertiaTimeConstant	number	280	Inertia time constant in ms.
inertiaVelocityMultiplier	number	18	Release velocity multiplier.
containerClassName	string	-	Classes on the outer stage.
ringClassName	string	-	Classes on the rotating ring.
imageClassName	string	-	Classes on each face plate.