Slideshow

Cycle through background images automatically with cross-fade transitions and optional progress dots.

Slideshow is a client component that autoplays a list of photos as full-bleed CSS background images, animating between them with motion. Use it for hero areas and visual backdrops. It fills its parent, so the parent needs an explicit size; it reads theme tokens and should render inside DesignSystemProvider.

Import#

typescript

import { Slideshow, wrap } from "@reactberry/system/blocks";

Usage#

typescript

import { Slideshow } from "@reactberry/system/blocks";
import { Box } from "@reactberry/system/elements";

const photos = [
  { id: 1, url: "/hero/one.jpg" },
  { id: 2, url: "/hero/two.jpg" },
  { id: 3, url: "/hero/three.jpg" },
];

export default function Hero() {
  return (
    <Box position="relative" width="100%" height="24rem">
      <Slideshow photos={photos} duration={5} showProgress />
    </Box>
  );
}

Examples#

Without the gradient overlay#

Set fade={false} to show the photos without the gradient. duration sets how many seconds each slide stays visible.

Single photo#

With one photo there is no autoplay, overlay or dots. The image is absolutely positioned, so the parent needs position="relative".

API#

Slideshow#

Prop	Type	Default	Description
`photos*`	`ImageType[]`	—	Images to show, as `{ id, url }`. Only `url` is read.
`showProgress`	`boolean`	—	Shows a row of clickable dots at the bottom. Clicking a dot jumps to that slide and restarts the autoplay timer.
`duration`	`number`	`3`	Seconds each slide stays visible before advancing.
`fade`	`boolean`	`true`	Renders a gradient overlay from transparent to `currentColor` over the images.

No other props are accepted and nothing is spread.

wrap#

wrap(min, max, v) wraps v into the range from min (inclusive) to max (exclusive). Slideshow uses it to map the current page to a photo index.

Prop	Type	Default	Description
`min*`	`number`	—	Lower bound, inclusive.
`max*`	`number`	—	Upper bound, exclusive.
`v*`	`number`	—	Value to wrap. `wrap(0, 3, 4)` returns `1`; `wrap(0, 3, -1)` returns `2`.

Accessibility#

Images are CSS backgrounds, so they have no alternative text.
The progress dots are div elements without a button role, label, or keyboard focus.
The component does not check for reduced-motion preferences, and autoplay cannot be paused.

Notes#

With an empty photos array the component renders a box containing the text "No images available".
With two or more photos, autoplay advances every duration seconds and loops back to the first photo.
Slides enter and exit with a 0.6 second opacity, scale, and vertical offset animation.
The fade overlay uses currentColor, so the inherited text colour determines its tint.