Full-height stories that play in turn under a progress bar each. Tap to step, hold to pause.
'use client';
import { StoryViewer } from '@brand-studio/ui';
import { beans, cup, pour } from '@/demos/assets';
export default function StoryViewerDemo() {
return (
<div style={{ width: '100%', maxWidth: 320 }}>
<StoryViewer label="Still Coffee stories" author={{ name: 'Still Coffee' }} time="5h" slides={[
{ id: 'beans', asset: beans, title: 'Huila, rested nine days', text: 'Roasted on Tuesday. Ready to brew from today.' },
{ id: 'pour', asset: pour, title: '15 g, 250 ml, three minutes', text: 'Pour in three stages. If it tastes sour, grind a little finer.' },
{ id: 'cup', asset: cup, title: 'Tasting on Saturday', text: 'Six coffees from one farm at 10:00. Four seats left.' },
]} />
</div>
);
}Installation
pnpm add @brand-studio/uinpm install @brand-studio/uiyarn add @brand-studio/uibun add @brand-studio/uiInstall the peer dependencies
npm install react react-domImport the stylesheet once
import '@brand-studio/ui/styles.css';Wrap your app in a brand theme
import { BrandTheme, StoryViewer } from '@brand-studio/ui'; import brand from './brand.json'; <BrandTheme palette={brand.tokens} mode="system"> {/* your app */} </BrandTheme>
Usage
import { StoryViewer } from '@brand-studio/ui';<StoryViewer
label="Still Coffee stories"
author={{ name: 'Still Coffee' }}
time="5h"
slides={[
{ id: 'beans', asset: beans, title: 'Huila, rested nine days', text: 'Ready to brew from today.' },
{ id: 'pour', asset: pour, title: '15 g, 250 ml, three minutes', duration: 7000 },
{ id: 'cup', asset: cup, title: 'Tasting on Saturday' },
]}
onEnd={() => setOpen(false)}
/>Each slide stays for duration milliseconds, five seconds unless you set it, while its bar fills; then the next slide comes in. Tap the right two thirds for the next slide and the left third to go back. Hold anywhere to pause and hide the captions so the picture shows clearly. After the last slide the viewer stops and calls onEnd; the play button then starts again from the first.
The frame is 9:16 and up to 24 rem wide. Images fill it from their focal point, so set focalPoint on a wide image to keep its subject in view. Write captions short: they sit on a dark scrim at the bottom.
Accessibility
- The viewer is a carousel named by
label. Each slide is a group named 2 of 3 and so on. - Previous and next are real buttons, and a visible button pauses and plays.
- With focus on the viewer, the arrow keys step and Space pauses.
- While paused, a new slide is announced; while playing, it is not.
- With reduced motion, the viewer starts paused and the pictures do not drift. The progress bar still fills once you press play.
API Reference
| Prop | Type | Default |
|---|---|---|
slides | StorySlide[] | – |
author | { name: string; avatar?: React.ReactNode; } | – |
time? | string | – |
duration? | number | – |
label? | string | – |
onEnd? | (() => void) | – |
className? | string | – |


