Image Accordion

Installation & usage

npm i @youj/react

For an app already set up with npx @youj/cli init, which installs the peers (@youj/core, @youj/motion, motion and Base UI) and wires the provider. New app? Start at Installation.

Use an image accordion to show a handful of pictures in the room of one: destinations, product shots, case studies. One panel is open wide with its title and a short line; the others stay visible as strips, so the whole set reads at a glance. For a long sequence to step through, use a Carousel.

import { ImageAccordion, type ImageAccordionItem } from '@youj/react'

const places: ImageAccordionItem[] = [
  { id: 'coast', media: { src: '/coast.jpg', alt: 'Coast road at sunrise' }, title: 'Coast road', description: 'Morning light over the headland' },
  { id: 'dunes', media: { src: '/dunes.jpg', alt: 'Sand dunes at dusk' }, title: 'Dunes', description: 'Wind-cut ridges at dusk' },
  { id: 'valley', media: <MyIllustration />, title: 'Valley' },
]

<ImageAccordion items={places} />

media is { src, alt } for an image (it covers the panel) or any node: an illustration, a video, a gradient. The first panel is open at first; value, defaultValue and onValueChange hold the open id.

With activation="hover" (the default) a panel opens when the pointer rests on it or it takes focus, and on touch when it's tapped. activation="click" opens only on a press, Enter or Space, and hover and the arrow keys just point. orientation="vertical" stacks the panels.

The component keeps its size: the panels share its box (h-80 across, h-120 stacked), so opening one only moves the split. Set your own height with className.

Reference

Propsitems, value, activation, orientation… (7)

Props

ImageAccordion props
Prop	Type	Default
`items`Required	`ImageAccordionItem[]`	–
`value`	`string` The open panel's id (controlled).	–
`defaultValue`	`string` The panel open at first. Default: the first.	–
`onValueChange`	`(id: string) => void` Called with the id of the panel that opens.	–
`activation`	`'hover' \| 'click'` `hover` opens a panel on hover or focus (a press on touch); `click` only on a press. default 'hover'	`'hover'`
`orientation`	`'horizontal' \| 'vertical'` Panels side by side (`horizontal`) or stacked (`vertical`). default 'horizontal'	`'horizontal'`
`aria-label`	`string` Names the group. Default: the labels' "Gallery".	–
`sound`	`boolean` With sound on (`YoujProvider`’s `sound`), opening a panel by press or key plays `select`; hovering stays silent. `false` keeps this one silent. default true	`true`
Other props pass through: extends `ComponentProps<'div'>`.

Items

ImageAccordionItem props
Prop	Type	Default
`id`Required	`string`	–
`media`Required	`ReactNode \| { src: string; alt: string }` The picture: `{ src, alt }` for an image, or your own node (an illustration, a video, a gradient). It fills the panel.	–
`title`Required	`ReactNode` The caption's first line, and the panel's accessible name.	–
`description`	`ReactNode` A short line under the title.	–

StylingParts and data attributes

MotionSplit, caption, strips · reduced motion

Motion

Motion tokens
Moment	Tokens	Value
Splitthe opening panel widens as the others narrow, retargeting mid-glide	`spring.smooth` 0.36s, bounce 0	0.36s, bounce 0
Captionfades up once its panel has started to open	`duration.baseease.enter` 220ms · cubic-bezier(0.16, 1, 0.3, 1)	220mscubic-bezier(0.16, 1, 0.3, 1)
Stripssit a little quieter, and brighten under the pointer	`duration.baseease.standard` 220ms · cubic-bezier(0.2, 0, 0, 1)	220mscubic-bezier(0.2, 0, 0, 1)

Reduced motion

The split and the caption jump.

Sound

With sound on (YoujProvider's sound), opening a panel by a press or a key plays select; hovering stays silent. sound={false} keeps one accordion quiet.

Reduced motion

The split and the caption jump; nothing glides.

AccessibilityGroup, buttons, keys