# React Native Stories, Instagram style (Pro)

> Instagram-style stories for React Native on iOS, Android and the web: a tray of avatars in gradient rings that turn grey once seen, and a full-screen viewer with segmented progress bars, tap to skip, hold to pause, a cube turn between people, drag down to close, photo and custom slides, a reply bar with quick reactions, and mute. No native modules. Part of Patine Pro.

# Stories Pro

`StoryTray` and `StoryViewer` are Instagram's stories: a row of avatars at the top of a feed, ringed in Instagram's gradient until you've seen them, and a full-screen viewer that plays each person's slides with segmented bars across the top. Tap the right side to go on and the left to go back, hold to pause, swipe sideways to the next person with a cube turn, and drag down to close. On wide screens the viewer is a phone-shaped frame in the middle with arrows beside it, as on Instagram's web.

Use it for social apps, but also for product updates ("What's new"), creators in a marketplace, daily recaps, or a course's lessons.

```tsx
import { StoryTray, StoryViewer } from '@patine-ui/pro';
```

```tsx live
import { useState } from 'react';
import { View } from 'react-native';
import { Text } from 'patine-ui';
import { StoryTray, StoryViewer } from '@patine-ui/pro';

const H = 3600000;
const NOW = Date.now();
const USERS = [
  {
    id: 'maya',
    name: 'Maya Lindqvist',
    avatar: 'https://i.pravatar.cc/150?img=47',
    verified: true,
    slides: [
      { id: 'm1', image: 'https://picsum.photos/id/1015/720/1280', createdAt: NOW - 2 * H, alt: 'A fjord from a cliff top' },
      { id: 'm2', image: 'https://picsum.photos/id/1016/720/1280', createdAt: NOW - H, alt: 'Canyon at sunset' },
      {
        id: 'm3',
        createdAt: NOW - 20 * 60000,
        render: () => (
          <View style={{ flex: 1, backgroundColor: '#4F46E5', alignItems: 'center', justifyContent: 'center', padding: 32 }}>
            <Text size="3xl" weight="semibold" style={{ color: '#fff', textAlign: 'center' }}>We launched.</Text>
            <Text size="lg" style={{ color: '#E0E7FF', textAlign: 'center', marginTop: 8 }}>Thank you, all 4,000 of you.</Text>
          </View>
        ),
      },
    ],
  },
  { id: 'leo', name: 'Leo Brandt', avatar: 'https://i.pravatar.cc/150?img=12', slides: [{ id: 'l1', image: 'https://picsum.photos/id/1036/720/1280', createdAt: NOW - 5 * H, hasAudio: true }] },
  { id: 'ana', name: 'Ana Souza', avatar: 'https://i.pravatar.cc/150?img=32', slides: [{ id: 'a1', image: 'https://picsum.photos/id/1043/720/1280', createdAt: NOW - 9 * H }] },
  { id: 'kai', name: 'Kai Tanaka', slides: [{ id: 'k1', image: 'https://picsum.photos/id/1050/720/1280', createdAt: NOW - 3 * H }] },
];

export default function Example() {
  const [users, setUsers] = useState(USERS);
  const [open, setOpen] = useState(null);
  const markSeen = (user, slide) =>
    setUsers((list) => list.map((u) => (u.id === user.id && u.slides[u.slides.length - 1].id === slide.id ? { ...u, seen: true } : u)));
  return (
    <View>
      <StoryTray users={users} onPress={(_, index) => setOpen(index)} onAddPress={() => {}} ownAvatar="https://i.pravatar.cc/150?img=5" />
      <StoryViewer
        users={users}
        visible={open !== null}
        initialUser={open ?? 0}
        onClose={() => setOpen(null)}
        onSlideSeen={markSeen}
        onReply={(user, slide, text) => console.log('reply', user.name, text)}
        onReact={(user, slide, emoji) => console.log('react', user.name, emoji)}
      />
    </View>
  );
}
```

Open a story, then try it: tap the right and left sides, hold to pause, drag sideways, drag down to close. On the web, the arrow keys step, Space pauses and Escape closes.

## Example: a shop's stories

A clothing shop's app: each collection is a story in the tray, the slides are product photos with a Shop now card, and replies go to the shop's inbox. A collection turns grey once you've seen its last slide.

```tsx live
import { useState } from 'react';
import { View } from 'react-native';
import { Button, Text } from 'patine-ui';
import { StoryTray, StoryViewer } from '@patine-ui/pro';

const H = 3600000;
const NOW = Date.now();
const product = (name: string, price: string) => () => (
  <View style={{ flex: 1, justifyContent: 'flex-end', padding: 24, backgroundColor: '#1C1917' }}>
    <View style={{ backgroundColor: '#fff', borderRadius: 16, padding: 16, gap: 8 }}>
      <Text weight="semibold">{name}</Text>
      <Text color="textSecondary">{price} · free returns</Text>
      <Button>Shop now</Button>
    </View>
  </View>
);
const USERS = [
  {
    id: 'linen',
    name: 'Linen edit',
    avatar: 'https://picsum.photos/id/1027/150/150',
    slides: [
      { id: 'l1', image: 'https://picsum.photos/id/1027/720/1280', createdAt: NOW - 3 * H, alt: 'A model in a sand linen shirt' },
      { id: 'l2', createdAt: NOW - 3 * H, render: product('Linen shirt, sand', '€59') },
    ],
  },
  { id: 'denim', name: 'Denim', avatar: 'https://picsum.photos/id/1011/150/150', slides: [{ id: 'd1', image: 'https://picsum.photos/id/1011/720/1280', createdAt: NOW - 8 * H, alt: 'Wide-leg jeans on a pier' }] },
  { id: 'sale', name: 'Last sizes', avatar: 'https://picsum.photos/id/1062/150/150', slides: [{ id: 's1', createdAt: NOW - H, render: product('Up to 40% off', 'From €19') }] },
];

export default function Example() {
  const [users, setUsers] = useState(USERS);
  const [open, setOpen] = useState<number | null>(null);
  const [replies, setReplies] = useState(0);
  return (
    <View style={{ gap: 8 }}>
      <StoryTray users={users} onPress={(_, index) => setOpen(index)} />
      <Text size="sm" color="textSecondary">{replies ? `${replies} replies sent to the shop` : 'Press a collection to watch it.'}</Text>
      <StoryViewer
        users={users}
        visible={open !== null}
        initialUser={open ?? 0}
        onClose={() => setOpen(null)}
        onSlideSeen={(user, slide) =>
          setUsers((list) => list.map((u) => (u.id === user.id && u.slides[u.slides.length - 1].id === slide.id ? { ...u, seen: true } : u)))
        }
        onReply={() => setReplies((n) => n + 1)}
      />
    </View>
  );
}
```

## Seen and unseen

The tray puts people you haven't seen first, each in Instagram's gradient ring; once their `seen` is true the ring goes grey and they move to the end. `onSlideSeen` fires as each slide shows: mark the person seen when their last slide does, and send the view to your API.

## Custom slides

A slide can be a photo (`image`, a URL or a `require()`) or anything you `render`: a poll, a product with a Shop button, a quote, a chart, or a video player of your own. `render` gets `{ paused, muted, active }`, so a video can pause while the slide is held and follow the mute button. Set `hasAudio` to show that button, and `duration` for a slide that needs longer than five seconds.

```tsx
{
  id: 'drop',
  duration: 8000,
  hasAudio: true,
  render: ({ paused, muted }) => <ProductVideo source={drop.video} paused={paused} muted={muted} />,
}
```

## Replies and reactions

Give `onReply` for the reply bar and `onReact` for the heart and quick reactions. Focusing the reply pauses the story and shows the reactions above it; sending shows "Sent", and a reaction pops on the slide.

## Transition

People change with a cube turn, as on Instagram. `transition="slide"` slides them side by side instead.

## Accessibility

- Each slide is one button that reads the person's name and the slide's place ("Maya's story, 2 of 3"), with Next and Previous actions for screen readers, and a photo's `alt` as its label.
- The viewer is a modal dialog; Android's back button and Escape close it.
- Close, mute, like and send are 44-point buttons with names.
- Bars fill and pages turn on the native driver; with reduce motion on, they move without animating, and the clock still runs.

## Props

### StoryTray

| Prop | Type | Default |
| --- | --- | --- |
| `users` | `StoryUser[]` | |
| `onPress` | `(user, index) => void` | |
| `onAddPress` | `() => void`: adds "Your story" first | |
| `ownAvatar` | `string \| ImageSource` | |
| `size` | `number`, the avatar | `64` |

### StoryViewer

| Prop | Type | Default |
| --- | --- | --- |
| `users` | `StoryUser[]` | |
| `visible` | `boolean` | |
| `initialUser` | `number` | `0` |
| `onClose` | `() => void` | |
| `onSlideSeen` | `(user, slide) => void` | |
| `onReply` | `(user, slide, text) => void`: shows the reply bar | |
| `onReact` | `(user, slide, emoji) => void`: shows the heart and reactions | |
| `transition` | `'cube' \| 'slide'` | `'cube'` |
| `reactions` | `string[]` | 😂 😮 😍 😢 👏 🔥 |
| `now` | `number`: pins "2h" in tests | now |

### StoryUser and StorySlide

`StoryUser`: `{ id, name, avatar?, slides, seen?, verified? }`. `StorySlide`: `{ id, image?, render?, duration? (5000), createdAt?, hasAudio?, alt? }`.

## Related

- [Image viewer](./image-viewer): a full-screen photo with zoom, free.
- [Swipe deck](./card-stack): Tinder's cards, the other half of a social app.
- [Avatar](./avatar): avatars and their fallbacks, free.
