---
outline: deep
---

# Story

A single story declaration inside [`<l-stories>`](/elements/stories). Renders the clickable thumbnail; the [viewer](/elements/stories-viewer) reads its `src`, `poster`, `label`, `chapters`, and `tracks` to play it. See [Stories](/elements/stories) for examples and the row layout.

**`<l-story>`** — Custom Element (no Shadow DOM)

## API reference

### Importing

```js
import 'luxen-ui/story';
```

```css
@import 'luxen-ui/css/story';
```

### Attributes & Properties

- **src**: `string` — Video URL.
- **poster**: `string` — Thumbnail poster image. Falls back to the first video frame.
- **preview**: `string` — Optional short looping preview video (URL of a small dedicated MP4, typically 2-3s, 480p, no audio). When set, the thumbnail renders this video muted+looped+autoplayed in place of `poster`. Gated by an `IntersectionObserver` so off-screen previews don't play.
- **label**: `string` — Caption shown below the thumbnail (or overlaid, depending on appearance) and used as the trigger `aria-label`.
- **duration**: `number` (default: `0`) — Override the progress duration in seconds. Defaults to the video's metadata duration.
- **seen**: `boolean` (default: `false`) — Mark this story as already viewed (faded ring). Reflected.
- **pulse**: `boolean` (default: `false`) — Pulse the thumbnail with an animated halo + a subtle scale tap to draw attention. Reflected.
- **chapters**: `string` — Chapter start times within the video, comma-separated seconds (e.g. `0,5,12,20`). `0` is implicit if omitted. Empty = single chapter spanning the full video.
- **tracks**: `string` — Comma-separated VTT track URLs for captions.

### Methods

- **getChapterStarts()** → `number[]` — Parsed chapter start times. Always begins with `0`, sorted, deduplicated. Empty `chapters` returns `[0]`.

### Slots

- **cta** — Overlay surfaced by the viewer when this story is active (e.g. product card, link).
- **header** — Header overlay (e.g. avatar + author).

### CSS classes

- `.l-story-trigger` — The clickable thumbnail button wrapper.
- `.l-story-thumb` — The poster/video thumbnail frame (ring + offset).
- `.l-story-play` — The centered play-icon overlay.
- `.l-story-label` — The caption text below the thumbnail.

### CSS custom properties

The thumbnail layout tokens (`--size`, `--radius`, `--ring-color`, `--ring-color-seen`, `--ring-width`, `--ring-offset`, `--ring-offset-color`, `--label-color`) are declared on `<l-stories>` and cascade to every story. See [Stories › CSS custom properties](/elements/stories#css-custom-properties). The play-icon disc is styled inline; consumers can override it by targeting `.l-story-play l-icon`.

The pulse animation has its own knobs:

- `--pulse-color` — Color of the attention pulse ring (only with the `pulse` attribute).
- `--pulse-scale` (default: `1.2`) — Peak scale of the pulse animation.
- `--pulse-duration` (default: `1.6s`) — Duration of one pulse cycle.