# Story Viewer

> Full-height stories that play in turn under a progress bar each. Tap to step, hold to pause.

```tsx
'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

```sh
npm install @brand-studio/ui
```

React 18 or 19 is a peer dependency. Import the stylesheet once and wrap the app in a brand theme:

```tsx
import '@brand-studio/ui/styles.css';
import { BrandTheme, StoryViewer } from '@brand-studio/ui';
import brand from './brand.json';

<BrandTheme palette={brand.tokens} mode="system">
  {/* your app */}
</BrandTheme>
```

## Usage

```tsx
import { StoryViewer } from '@brand-studio/ui';
```

```tsx
<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` | – |

Source: https://brandstudio.js.org/docs/components/story-viewer/
