# Story Ring

Avatar in an accent story ring when there’s something new, which sweeps down to a thin line once viewed. While posting, the ring fills with the upload’s progress.

> Composed · Pro · Data Display — React Native, Expo Go compatible.

## Install

```bash
npx @lumioui/cli add pro/story-ring
```

## Import

```tsx
import { StoryRing } from "@/components/ui/story-ring/story-ring";
```

## Variants

- `highlights` — Profile highlights: `npx @lumioui/cli add pro/story-ring-highlights`
- `status` — Status updates: `npx @lumioui/cli add pro/story-ring-status`
- `tray` — Crew updates: `npx @lumioui/cli add pro/story-ring-tray`

## Props

| Prop | Type | Notes |
| --- | --- | --- |
| `source?` | `ImageSourcePropType` | Avatar image. |
| `fallback?` | `string` | Initials when there is no image (or it fails). |
| `size?` | `"sm" | "md" | "lg" | "xl"` | Outer diameter: sm 44 · md 64 · lg 76 · xl 96. Default "md". |
| `seen?` | `boolean` | Every story has been viewed — the light dims clockwise to a hairline. |
| `segments?` | `number` | Split the ring per story (status lists). Default 1. |
| `seenSegments?` | `number` | How many leading segments are already viewed. |
| `live?` | `boolean` | Broadcasting now — adds the Live badge. |
| `closeFriends?` | `boolean` | Close-friends story — green ring. |
| `tone?` | `"gradient" | "accent"` | Unseen ring colour: the surrounding <Accent> primary as a lit ring  (default), or a gradient (opt-in; also implied by `colors`). |
| `colors?` | `string[]` | Gradient stops for the unseen ring. |
| `addBadge?` | `boolean` | "+" badge for the viewer's own story. Turning it off right after a  post lands dims it away once the post has held. |
| `loading?` | `boolean` | Upload in progress. With `progress` the ring draws round with it;  without, it laps until the upload lands. |
| `progress?` | `number` | Upload progress 0–1 while `loading` — value-coupled, no spinner. |
| `labelClassName?` | `string` | Extra classes for the label (seen rings mute it by default). |
| `label?` | `string` | Name under the ring, truncated to the ring's column. |
| `surfaceClassName?` | `string` | Classes for the badge border — match the surface the ring sits on.  Default "border-background". |
| `className?` | `string` | — |

## Icons rendered

- `user` — /icons.html?i=user
- `plus` — /icons.html?i=plus

Source: https://lumioui.com/components/story-ring