Media / COMPONENT

Image Accordion

A selectable image stack that animates the chosen image into a preview canvas while keeping the full collection in rotation.

Live preview
Image stack05 / 05 images

Preview

Select a corner to reveal an image.

View the Image Accordion source on GitHub

How it works

The selected card animates into the preview canvas and moves to the back of the stack. When there are more items than the visible count, the next image rotates into view.

Accessibility

Image cards are keyboard operable and use the supplied alt text. Captions can describe each image, and reduced-motion preferences disable the spring transitions.

Limitations

The component renders the image URLs supplied by the consuming app; image hosting, loading behavior, and accurate alt text remain the app author’s responsibility. The initial images collection is used to initialize its interactive stack.

Features

  • Accepts any number of images; five cards are shown in the stack by default.
  • Selecting a card animates that same image into the preview canvas and moves it to the end of the collection.
  • When the collection has more images than visibleCount, the next image rotates into view as cards are selected.
  • Customize wrapper, stack, card, preview, and image classes globally or per image item.
  • Tune the radial glow color, position, size, opacity, and blur, or disable it with glow={false}.
  • Configure the shared spring with stiffness, damping, and mass.
  • Supports keyboard activation, image alt text, captions, and reduced-motion preferences.

Installation

Choose the CLI command or install the component manually.

Package manager
$ npx @istmx/ui add image-accordion

Copies the install command for your selected package manager.

Dependencies

ReactMotionTailwind CSSclsxtailwind-merge

Usage

Import the component from the file you copied it to, then use it like any other React component.

Usage
import ImageAccordion from '@/components/ui/image-accordion'
 
const images = [
  { src: '/images/one.jpg', alt: 'Coastal cliffs', title: 'The coast' },
  { src: '/images/two.jpg', alt: 'A quiet forest', title: 'The forest' },
  { src: '/images/three.jpg', alt: 'A city at dusk', title: 'The city' },
  { src: '/images/four.jpg', alt: 'A mountain lake', title: 'The lake' },
  { src: '/images/five.jpg', alt: 'A desert path', title: 'The desert' },
  { src: '/images/six.jpg', alt: 'Snowy peaks', title: 'The peaks' },
]
 
<ImageAccordion
  images={images}
  visibleCount={5}
  className="mx-auto max-w-5xl"
  stackClassName="md:pr-4"
  cardClassName="rounded-lg"
  imageClassName="object-cover"
  previewClassName="min-h-80"
  glow={{ color: '#d4d4d8', opacity: 0.2, blur: 16 }}
  transition={{ stiffness: 190, damping: 24, mass: 0.8 }}
/>

Composition

Composition
ImageAccordion
├── Image stack (up to visibleCount cards)
│   └── Selectable image cards
└── Preview canvas
    └── Selected image and optional caption

API reference

imagesImageAccordionItem[]

The full image collection. Each item accepts id?, src, alt, title, description?, className?, and imageClassName?. Add unique id values if the same src can appear more than once.

visibleCount?number

Maximum cards shown in the stack. Defaults to 5; values are rounded down and clamped to at least 1. The full collection remains available and rotates through the visible stack.

className?string

Tailwind classes applied to the outer component layout.

stackClassName?string

Classes applied to the image-stack column wrapper.

cardClassName?string

Classes applied to every selectable card. An item className adds per-card styling through cn().

imageClassName?string

Classes applied to thumbnail and preview images. An item imageClassName adds per-image styling.

previewClassName?string

Classes applied to the preview canvas.

glow?false | ImageAccordionGlow

Set false to disable the glow; otherwise configure color?, position?, size?, opacity?, and blur?. Defaults to a restrained foreground radial glow.

transition?{ stiffness?: number; damping?: number; mass?: number }

Spring values for the shared image transition. Defaults to stiffness 190, damping 24, and mass 0.8.

The listed props match the current component implementation.

Data attributes

Image Accordion does not expose custom data attributes.

Examples

Pass a collection of any length. Five items are visible by default; selecting a visible image moves it to the end and brings the next item into the stack. Set visibleCount to change the visible window, and use className fields to style the layout or individual images.

Credits & inspiration

Created by Aryan (istmX) for ISTMX. The source-first, copy-and-own philosophy is inspired by shadcn/ui. About the creator