Story Rail

When to use

Reach for StoryRail when you need a horizontal stories rail at the top of a feed — kasder-style portrait thumbnails with a gradient ring (unread) or muted ring (read), drag-free skim-scroll, and edge-fade gradients. Decoupled from the viewer: onItemClick({ item, index }) hands off to whatever your host renders (your own viewer, the future story-viewer, a navigation push, etc.).

Footgun: the `items` prop is mount-only

Component captures items as initial state on mount; subsequent prop reference changes are ignored. Realtime subscribemutates the internal store; for external pushes use the imperative handle's reset(next) or surgical dispatch(action).

Minimal usage

import { StoryRail } from "@/components/story-rail";

<StoryRail
  items={stories}
  onItemClick={({ item, index }) => openViewer(index)}
/>

With AddStoryThumbnail (kasder UX)

import {
  StoryRail,
  AddStoryThumbnail,
} from "@/components/story-rail";

<StoryRail
  items={stories}
  leading={
    <AddStoryThumbnail
      userAvatar={viewer.avatar}
      onClick={() => openStoryComposer()}
    />
  }
  onItemClick={({ item, index }) => openViewer(index)}
/>

Realtime via subscribe

import type {
  Subscribe,
  StoryRailDelta,
} from "@/components/story-rail";

const subscribe = useCallback<Subscribe<StoryRailDelta>>(
  (handler) => channel.on("stories", handler),
  [channel],
);

<StoryRail
  items={stories}
  subscribe={subscribe}
  onSubscribeDelta={(d) => analytics.track("story-rail-delta", d)}
/>

Hosts must memoize subscribe via useCallback — identity changes trigger a clean teardown + re-call (same convention as engagement-bar / comment-thread / post-card).

Mark viewed (from your viewer's onClose)

const railRef = useRef<StoryRailHandle>(null);

<StoryRail
  ref={railRef}
  items={stories}
  onItemClick={({ item, index }) => {
    setActiveStoryIndex(index);
    setViewerOpen(true);
  }}
/>

<MyStoryViewer
  open={viewerOpen}
  story={stories[activeStoryIndex]}
  onClose={() => {
    setViewerOpen(false);
    railRef.current?.markViewed(stories[activeStoryIndex].id);
  }}
/>

Click does NOT auto-mark-viewed (matches Instagram — the ring stays until the user actually completes the story). Host calls markViewed(itemId) when their viewer closes.

Custom thumbnail render

<StoryRail
  items={stories}
  renderThumbnail={(item, isUnread, { onClick, baseId }) => (
    <BrandedStoryThumbnail
      item={item}
      isUnread={isUnread}
      onClick={onClick}
      ariaLabelledBy={baseId}
    />
  )}
/>

Bare (no card frame)

<StoryRail items={stories} framed={false} className="px-4" />

With framed: false, the card chrome is removed and the edge gradients use from-background + left-0/right-0 so they blend with whatever container you embed in.

Notes

• Embla used inline with align: "start", containScroll: "trimSnaps", dragFree: true (kasder-exact). No indicator dots — story rails are skim-scroll, not snap carousels.
• Thumbnail dimensions locked to w-20 h-28 (80×112). For different sizes, use the renderThumbnail slot.
• Unread ring: bg-linear-to-br from-accent via-warning to-destructive. Read ring: bg-muted.
• Edge gradients are aria-hidden + pointer-events-none; don't intercept drag.
• StoryRailItem.previewImage is required (no placeholder fallback in v0.1). Hosts ensure preview URLs exist before passing.
• linkComponent + getHref co-exist with onItemClick — both fire on click. Use this for analytics on a navigation-mode rail.
• For external state coordination, the storyRailReducer and useStoryRailState are publicly exported.