Skip to content
ilinxa/pro-ui

Story Rail

alphav0.4.0

Horizontal story rail with unread gradient rings, drag-free skim scrolling, optional arrows, an add-story tile, and scroll-aware edge fades.

Category: Data DisplayUpdated: 2026-10-23Created: 2026-05-03Author: ilinxa

Context

Seventh of 8 in the social-posts-system arc — story doublet, part 1. Embla used directly (sealed-folder rule — story-rail's start-aligned + drag-free + small-rectangle config differs structurally from media-carousel's centered + snap + large-square gallery). Migration origin: kasder kas-social-front-v0 StoriesSection.tsx + StoryThumbnail.tsx. Realtime contract identical shape to engagement-bar / comment-thread / post-card — single Subscribe<TDelta> mental model across the family. Click does NOT auto-mark-viewed (matches Instagram); host calls ref.current.markViewed(itemId) when their viewer closes. Edge fades adapt to framed mode (from-card when wrapped in card chrome, from-background when bare) and show only on a side the rail can scroll toward. v0.4 hardening for the ilinxa Social Platform: optional preview with an avatar-card fallback, story-ring tokens, muted authors, opt-in arrows, controlled items, RTL. Pairs with story-viewer for the full doublet — viewer takes the FULL Story shape with items[] inner content; rail takes a minimal preview shape. TypeScript structural typing means hosts can pass a Story to story-rail if its fields are a superset; no adapter needed.

Installation

Initialize shadcn (once per project)Seeds lib/utils.ts and components.json. Skip if you've already used any shadcn component.
pnpm dlx shadcn@latest init
Install the component
pnpm dlx shadcn@latest add @ilinxa/story-rail

Add -fixtures for dummy data:

pnpm dlx shadcn@latest add @ilinxa/story-rail-fixtures

CLI can't resolve @ilinxa? The namespace is listed in the official shadcn registry directory, so current CLIs need no configuration. If yours can't resolve it (older or pinned versions, self-hosted mirrors), register it manually in components.json:

"registries": {
  "@ilinxa": "https://ui.ilinxa.com/r/{name}.json"
}

Preview

Demo source

demo.tsxtsx
"use client"; import { useMemo, useRef, useState } from "react";import { Button } from "@/components/ui/button";import { Tabs, TabsContent, TabsTrigger } from "@/components/ui/tabs";import { SwipeTabsList } from "@/components/site/swipe-tabs-list";import { StoryViewer } from "../../media/story-viewer";import type { Story } from "../../media/story-viewer";import { StoryRail } from "./story-rail";import { AddStoryThumbnail } from "./parts/add-story-thumbnail";import {  DUMMY_STORIES,  DUMMY_VIEWER_AVATAR,  createDummyStoryRailSubscribe,} from "./dummy-data";import type { StoryRailHandle, StoryRailItem } from "./types"; function log(tag: string, payload: unknown) {  if (typeof console !== "undefined") {    console.log(`[demo:story-rail:${tag}]`, payload);  }} const NOW = new Date("2026-05-03T14:00:00Z");const isoMinusMin = (min: number) =>  new Date(NOW.getTime() - min * 60_000).toISOString(); /** * Real Unsplash + w3schools URLs (verified working) cycled across the rail items * so the viewer's nav arrows + tap zones visibly advance to a different image * each time. Demo-only — NOT in dummy-data.ts (which ships via story-rail-fixtures * and stays viewer-free). */const SECONDARY_IMAGES = [  "https://images.unsplash.com/photo-1469474968028-56623f02e42e?w=900&h=1600&fit=crop",  "https://images.unsplash.com/photo-1500530855697-b586d89ba3ee?w=900&h=1600&fit=crop",  "https://images.unsplash.com/photo-1454496522488-7a8e488e8606?w=900&h=1600&fit=crop",  "https://images.unsplash.com/photo-1504805572947-34fad45aed93?w=900&h=1600&fit=crop",  "https://images.unsplash.com/photo-1418065460487-3e41a6c84dc5?w=900&h=1600&fit=crop",  "https://images.unsplash.com/photo-1444080748397-f442aa95c3e5?w=900&h=1600&fit=crop",  "https://images.unsplash.com/photo-1505765050516-f72dcac9c60e?w=900&h=1600&fit=crop",]; /** * Full-Story shape for the viewer, derived from a rail item (same id). Rail * items are minimal previews; the viewer needs full items[] + createdAt. * Items without a preview fall back to a SECONDARY_IMAGES entry (modulo, so the * array length never matters). */function toFullStory(rail: StoryRailItem, idx: number): Story {  const first =    rail.previewImage ?? SECONDARY_IMAGES[idx % SECONDARY_IMAGES.length];  const second = SECONDARY_IMAGES[(idx + 1) % SECONDARY_IMAGES.length];  return {    id: rail.id,    userId: rail.userId ?? `u${idx + 1}`,    username: rail.username,    avatar: rail.avatar,    hasUnread: rail.hasUnread,    createdAt: isoMinusMin((idx + 1) * 18),    items:      idx === 1        ? [            { id: `${rail.id}-i1`, type: "video", src: "https://www.w3schools.com/html/mov_bbb.mp4" },            { id: `${rail.id}-i2`, type: "image", src: first, duration: 5 },          ]        : idx === 4          ? [              { id: `${rail.id}-i1`, type: "image", src: first, duration: 5 },              { id: `${rail.id}-i2`, type: "video", src: "https://www.w3schools.com/html/movie.mp4" },            ]          : [              { id: `${rail.id}-i1`, type: "image", src: first, duration: 5 },              { id: `${rail.id}-i2`, type: "image", src: second, duration: 5 },            ],  };} type RailProps = React.ComponentProps<typeof StoryRail>; interface RailWithViewerProps {  framed?: boolean;  showAddLeading?: boolean;  renderThumbnail?: RailProps["renderThumbnail"];  subscribe?: RailProps["subscribe"];  /** Uncontrolled seed. Defaults to DUMMY_STORIES. */  defaultItems?: StoryRailItem[];  /** Controlled mode: pass `items` together with `onItemsChange`. */  items?: StoryRailItem[];  onItemsChange?: RailProps["onItemsChange"];  onPreviewError?: RailProps["onPreviewError"];  arrows?: RailProps["arrows"];  dir?: RailProps["dir"];  labels?: RailProps["labels"];  /** Custom `leading` node; wins over `showAddLeading`. */  leading?: RailProps["leading"];  /** Lets a parent reach the rail handle too (controlled tab). */  railRef?: React.RefObject<StoryRailHandle | null>;} /** * Shared rail+viewer wiring — the canonical pattern from the guide: * rail click sets activeIdx, viewer opens, viewer's onStoryViewed feeds back * into railRef.markViewed to clear the unread ring. */function RailWithViewer({  framed = true,  showAddLeading = false,  renderThumbnail,  subscribe,  defaultItems,  items,  onItemsChange,  onPreviewError,  arrows,  dir,  labels,  leading,  railRef: externalRef,}: RailWithViewerProps) {  const ownRef = useRef<StoryRailHandle | null>(null);  const railRef = externalRef ?? ownRef;  const [activeIdx, setActiveIdx] = useState(-1);   const controlled = items !== undefined && onItemsChange !== undefined;  const seed = items ?? defaultItems ?? DUMMY_STORIES;  const fullStories = useMemo(() => seed.map(toFullStory), [seed]);   const leadingNode =    leading ??    (showAddLeading ? (      <AddStoryThumbnail        userAvatar={DUMMY_VIEWER_AVATAR}        onClick={() => log("add-story", null)}      />    ) : undefined);   return (    <div className="mx-auto flex max-w-2xl flex-col gap-3">      <StoryRail        ref={railRef}        {...(controlled ? { items, onItemsChange } : { defaultItems: seed })}        framed={framed}        leading={leadingNode}        renderThumbnail={renderThumbnail}        subscribe={subscribe}        onSubscribeDelta={subscribe ? (d) => log("delta", d) : undefined}        onPreviewError={onPreviewError}        arrows={arrows}        dir={dir}        labels={labels}        onItemClick={({ item, index }) => {          log("click", { item, index });          setActiveIdx(index);        }}      />       {activeIdx >= 0 && fullStories[activeIdx] ? (        <StoryViewer          stories={fullStories}          initialStoryIndex={activeIdx}          isOpen          onClose={() => setActiveIdx(-1)}          onStoryViewed={(id) => {            log("story-viewed", id);            railRef.current?.markViewed(id);          }}          onAutoCloseAtEnd={() => log("auto-close-at-end", null)}        />      ) : null}    </div>  );} function DefaultTab() {  return <RailWithViewer />;} function WithAddTab() {  return <RailWithViewer showAddLeading />;} function MixedReadUnreadTab() {  return <RailWithViewer />;} function RealtimeTab() {  const subscribe = useMemo(() => createDummyStoryRailSubscribe(), []);  return <RailWithViewer showAddLeading subscribe={subscribe} />;} function CustomRenderTab() {  return (    <RailWithViewer      renderThumbnail={(item: StoryRailItem, isUnread, { onClick }) => (        <button          type="button"          onClick={onClick}          aria-label={item.username}          className="group flex h-20 w-20 shrink-0 items-center justify-center overflow-hidden rounded-2xl border-2 border-card bg-muted shadow-sm transition-transform hover:scale-105"        >          {item.previewImage ? (            <img              src={item.previewImage}              alt=""              className="h-full w-full object-cover"              style={{                filter: isUnread ? "saturate(1.1)" : "saturate(0.4)",              }}            />          ) : (            <span aria-hidden="true" className="h-full w-full bg-muted" />          )}        </button>      )}    />  );} function BareTab() {  return <RailWithViewer framed={false} showAddLeading />;} function EmptyTab() {  const [items] = useState<StoryRailItem[]>([]);  return (    <div className="mx-auto max-w-2xl">      <StoryRail defaultItems={items} />    </div>  );} const BROKEN_URL =  "https://images.unsplash.com/photo-0000000000000-broken?w=200";const RECOVERED_URL =  "https://images.unsplash.com/photo-1470071459604-3b5ec3a7fe05?w=400&h=600&fit=crop&q=80"; const FALLBACK_ITEMS: StoryRailItem[] = [  {    id: "fb-none",    userId: "fb1",    username: "no-preview",    avatar: DUMMY_STORIES[0]?.avatar,    hasUnread: true,  },  {    id: "fb-muted",    userId: "fb2",    username: "muted",    avatar: DUMMY_STORIES[1]?.avatar,    previewImage: DUMMY_STORIES[1]?.previewImage,    hasUnread: true,    muted: true,  },  {    id: "fb-recover",    userId: "fb3",    username: "recovers",    avatar: DUMMY_STORIES[2]?.avatar,    previewImage: BROKEN_URL,    hasUnread: true,  },  {    id: "fb-dead",    userId: "fb4",    username: "stays-broken",    avatar: DUMMY_STORIES[3]?.avatar,    previewImage: BROKEN_URL,    hasUnread: true,  },]; async function resolvePreview(item: StoryRailItem): Promise<string | void> {  log("preview-error", item.id);  // "recovers" gets a fresh URL (think: a re-signed one). Everything else  // resolves nothing, so the rail falls back to the avatar card.  if (item.id === "fb-recover") return RECOVERED_URL;} function FallbacksTab() {  return (    <div className="flex flex-col gap-3">      <RailWithViewer        defaultItems={FALLBACK_ITEMS}        onPreviewError={resolvePreview}      />      <p className="mx-auto max-w-2xl text-xs text-muted-foreground">        1: no <code>previewImage</code> (avatar card). 2: <code>muted</code> +        unread (grey ring). 3: broken URL, <code>onPreviewError</code> resolves        a working one. 4: broken URL, nothing resolves, so the avatar card.      </p>    </div>  );} let nextControlledId = 1; function ControlledTab() {  const railRef = useRef<StoryRailHandle | null>(null);  const [items, setItems] = useState<StoryRailItem[]>(() =>    DUMMY_STORIES.slice(0, 6),  );  const unread = items.filter((i) => i.hasUnread && !i.muted).length;   const addStory = () =>    setItems((prev) => {      const n = nextControlledId++;      const src = DUMMY_STORIES[(prev.length + n) % DUMMY_STORIES.length];      return [        {          ...src,          id: `ctl-${n}`,          userId: `ctl-u${n}`,          username: `new${n}`,          hasUnread: true,          muted: false,        },        ...prev,      ];    });  const flipFirst = () =>    setItems((prev) =>      prev.map((it, i) => (i === 0 ? { ...it, hasUnread: !it.hasUnread } : it)),    );  const reorder = () =>    setItems((prev) => (prev.length > 1 ? [...prev.slice(1), prev[0]] : prev));   return (    <div className="flex flex-col gap-3">      <RailWithViewer        railRef={railRef}        items={items}        onItemsChange={(next) => {          log("items-change", next.length);          setItems(next);        }}      />      <div className="mx-auto flex w-full max-w-2xl flex-wrap items-center gap-2">        <Button size="sm" variant="outline" onClick={addStory}>          Add story        </Button>        <Button size="sm" variant="outline" onClick={flipFirst}>          Flip first unread        </Button>        <Button size="sm" variant="outline" onClick={reorder}>          Reorder        </Button>        <span          data-testid="controlled-unread-count"          className="ms-auto font-mono text-xs text-muted-foreground"        >          {unread} unread / {items.length} total        </span>      </div>      <p className="mx-auto max-w-2xl text-xs text-muted-foreground">        Parent state owns the list. Open a story: the viewer calls{" "}        <code>markViewed</code>, the rail reports it through{" "}        <code>onItemsChange</code>, and the count above drops.      </p>    </div>  );} function ArrowsTab() {  const items = useMemo<StoryRailItem[]>(    () =>      Array.from({ length: 16 }, (_, i) => {        const base = DUMMY_STORIES[i % DUMMY_STORIES.length];        return { ...base, id: `arr-${i}`, username: `${base.username}${i + 1}` };      }),    [],  );  return (    <div className="flex flex-col gap-3">      <RailWithViewer defaultItems={items} arrows="always" showAddLeading />      <p className="mx-auto max-w-2xl text-xs text-muted-foreground">        <code>arrows=&quot;always&quot;</code> shows on touch screens too;        production consumers typically use{" "}        <code>arrows=&quot;fine-pointer&quot;</code>.      </p>    </div>  );} const RTL_LABELS: NonNullable<RailProps["labels"]> = {  railLabel: "القصص",  addStoryLabel: "أضف قصة",  addStoryAriaLabel: "أضف قصة جديدة",  previousLabel: "القصص السابقة",  nextLabel: "القصص التالية",  thumbnailAriaLabel: (item) =>    item.muted      ? `${item.username}، مكتومة`      : item.hasUnread        ? `${item.username}، قصة غير مقروءة`        : `${item.username}، تمت المشاهدة`,  emptyState: "لا توجد قصص بعد.",}; function RtlTab() {  const items = useMemo<StoryRailItem[]>(    () =>      Array.from({ length: 12 }, (_, i) => {        const base = DUMMY_STORIES[i % DUMMY_STORIES.length];        return { ...base, id: `rtl-${i}`, username: `${base.username}${i + 1}` };      }),    [],  );  return (    <div dir="rtl">      <RailWithViewer        defaultItems={items}        arrows="always"        labels={RTL_LABELS}        leading={          <AddStoryThumbnail            userAvatar={DUMMY_VIEWER_AVATAR}            onClick={() => log("add-story", null)}          />        }      />    </div>  );} export default function StoryRailDemo() {  return (    <Tabs defaultValue="default" className="w-full">      <SwipeTabsList>        <TabsTrigger value="default">Default</TabsTrigger>        <TabsTrigger value="add">+ Add</TabsTrigger>        <TabsTrigger value="mixed">Mixed</TabsTrigger>        <TabsTrigger value="realtime">Realtime</TabsTrigger>        <TabsTrigger value="custom">Custom</TabsTrigger>        <TabsTrigger value="bare">Bare</TabsTrigger>        <TabsTrigger value="empty">Empty</TabsTrigger>        <TabsTrigger value="fallbacks">Fallbacks</TabsTrigger>        <TabsTrigger value="controlled">Controlled</TabsTrigger>        <TabsTrigger value="arrows">Arrows</TabsTrigger>        <TabsTrigger value="rtl">RTL</TabsTrigger>      </SwipeTabsList>      <TabsContent value="default" className="mt-4">        <DefaultTab />      </TabsContent>      <TabsContent value="add" className="mt-4">        <WithAddTab />      </TabsContent>      <TabsContent value="mixed" className="mt-4">        <MixedReadUnreadTab />      </TabsContent>      <TabsContent value="realtime" className="mt-4">        <RealtimeTab />      </TabsContent>      <TabsContent value="custom" className="mt-4">        <CustomRenderTab />      </TabsContent>      <TabsContent value="bare" className="mt-4">        <BareTab />      </TabsContent>      <TabsContent value="empty" className="mt-4">        <EmptyTab />      </TabsContent>      <TabsContent value="fallbacks" className="mt-4">        <FallbacksTab />      </TabsContent>      <TabsContent value="controlled" className="mt-4">        <ControlledTab />      </TabsContent>      <TabsContent value="arrows" className="mt-4">        <ArrowsTab />      </TabsContent>      <TabsContent value="rtl" className="mt-4">        <RtlTab />      </TabsContent>    </Tabs>  );} 

Usage

When to use

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

Items: uncontrolled, controlled, legacy

  • Uncontrolled — defaultItems seeds the rail once on mount. markViewed, dispatch, reset and realtime subscribedeltas mutate the rail's internal list.
  • Controlled — pass items together with onItemsChange. The prop wins on every render. Every mutation (markViewed, dispatch, reset, subscribe deltas) is computed from the latest prop and reported through onItemsChange(next); the DOM changes only when your items do. Two deltas before a re-render both land. To discard a reported change, re-render with a fresh array; until items changes identity the rail keeps building on the last list it reported.
  • Notified uncontrolled — defaultItems plus onItemsChange: the rail keeps its own list and also reports every next list.
  • Legacy — items alone (no onItemsChange) is read once on mount and later changes are ignored. It still works, and a dev-only warning points you at defaultItems or onItemsChange.

Minimal usage (uncontrolled)

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

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

Controlled

const [stories, setStories] = useState(initialStories);
const railRef = useRef<StoryRailHandle>(null);

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

// viewer.onStoryViewed -> railRef.current?.markViewed(id)
// -> onItemsChange(next) -> setStories(next) -> rail re-renders

With AddStoryThumbnail

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

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

Inside a rail, AddStoryThumbnail reads labels.addStoryLabel and labels.addStoryAriaLabel from the rail through context, so you localize once. Its own label / ariaLabel props still win. Used standalone (outside a rail) it uses the English defaults. It shows a visible focus ring on keyboard focus.

Missing, broken or expired previews

<StoryRail
  defaultItems={stories}           // previewImage is optional
  onPreviewError={async (item) => {
    // Resolve a fresh URL (e.g. re-signed) -> retried once.
    // Resolve nothing, or reject -> avatar card.
    return await api.refreshStoryPreview(item.id);
  }}
/>

previewImage is optional. When it is absent, or it fails and onPreviewErrorcannot refresh it, the tile renders an avatar card: the author's avatar (initials fallback) centred on bg-muted, same 80×112 size. A new previewImage on the item resets the state. Pass previewSrcSet / previewSizes (sizes defaults to 80px) for responsive previews.

Muted authors

{ id: "9", username: "burak", hasUnread: true, muted: true, ... }

muted: truedraws the grey ring even when the story is unread, and renders the tile and name at reduced opacity. Ordering stays yours. The default aria label reads "{username}, muted".

Arrows

<StoryRail defaultItems={stories} arrows="fine-pointer" />

arrows is "none" (default), "fine-pointer" (mouse / trackpad only, resolved after mount so the first render matches the server) or "always". An arrow is hidden when the rail cannot scroll that way. Each press scrolls a page, arrows mirror in RTL, and prefers-reduced-motion jumps instead of animating. Names come from labels.previousLabel / labels.nextLabel. Without arrows, a mouse can only click-drag (there is no wheel / trackpad-swipe scrolling), so desktop layouts usually want "fine-pointer". Arrows sit on the default tile's centre; set --story-rail-arrow-top for custom tiles.

RTL and localization

<div dir="rtl">
  <StoryRail
    defaultItems={stories}
    arrows="always"
    leading={<AddStoryThumbnail userAvatar={viewer.avatar} />}
    labels={{
      railLabel: "القصص",
      addStoryLabel: "أضف قصة",
      addStoryAriaLabel: "أضف قصة جديدة",
      previousLabel: "القصص السابقة",
      nextLabel: "القصص التالية",
      emptyState: "لا توجد قصص بعد.",
    }}
  />
</div>

Direction comes from the dir prop, else the nearest [dir] ancestor (resolved after mount), and feeds Embla. Fades, the arrows and the Add badge use logical positions. Every string lives in labels (defaults in DEFAULT_STORY_RAIL_LABELS), including the thumbnailAriaLabel(item) function.

Realtime via subscribe

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

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

<StoryRail
  defaultItems={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. In controlled mode each delta is reported through onItemsChange instead of being applied internally.

Mark viewed (from your viewer)

const railRef = useRef<StoryRailHandle>(null);

<StoryRail
  ref={railRef}
  defaultItems={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. ref.scrollTo(index) takes an index into items; the leading slot is not counted.

Custom thumbnail render

<StoryRail
  defaultItems={stories}
  renderThumbnail={(item, isUnread, { onClick, baseId, showRing }) => (
    <BrandedStoryThumbnail
      item={item}
      preview={item.previewImage /* string | undefined */}
      ring={showRing /* hasUnread && !muted; isUnread is raw hasUnread */}
      onClick={onClick}
      ariaLabelledBy={baseId}
    />
  )}
/>

Bare (no card frame)

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

With framed: false, the card chrome is removed and the edge fades use from-background so they blend with whatever container you embed in.

Theming

:root {
  --story-ring-from: oklch(0.80 0.20 132);
  --story-ring-to: oklch(0.70 0.18 60);
  --story-rail-fade-width: 2rem; /* default 3rem */
}
.dark {
  --story-ring-from: oklch(0.86 0.18 132);
  --story-ring-to: oklch(0.75 0.16 60);
}

The unread ring is a gradient from --story-ring-from to --story-ring-to. Define them in your :root / .dark; the install adds --color-story-ring-* mappings with fallbacks that never override yours. The edge fades are scroll-aware: each shows only on a side the rail can scroll toward, so at rest the first tile and its focus ring are never covered. Width is --story-rail-fade-width.

Upgrading from 0.3

  • previewImage is optional: in renderThumbnail and any reducer reader it is now string | undefined. Guard before using it as an img src.
  • Move items= to defaultItems= (or add onItemsChange to control it). Bare items still works but dev-warns.
  • Ring colours are token-driven. The old from-accent via-warning to-destructive classes are gone; set --story-ring-from / --story-ring-to.
  • Edge fades are scroll-aware instead of always showing.
  • ref.scrollTo(index) now targets the item index even when leading is mounted.

Notes

  • Embla used inline with align: "start", containScroll: "trimSnaps", dragFree: true. No indicator dots — story rails are skim-scroll, not snap carousels.
  • Thumbnail dimensions are fixed at w-20 h-28 (80×112). For different sizes, use the renderThumbnail slot.
  • Edge fades are aria-hidden + pointer-events-none; they don't intercept drag.
  • 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.

Features

  • Kasder-exact thumbnail aesthetic — w-20 h-28 portrait, gradient ring (unread) vs muted ring (read), avatar+username row below
  • Optional `previewImage` — absent or failing → avatar card (author avatar on bg-muted); `onPreviewError(item)` can resolve a refreshed URL, retried once; lazy/async `<img>` with width/height/srcSet/sizes
  • Unread ring from `--story-ring-from` / `--story-ring-to` (item cssVars.theme mappings with fallbacks — your theme wins)
  • `muted` items — grey ring even when unread, tile + name at reduced opacity; the aria-label function receives the item
  • Opt-in previous / next arrows (`arrows="fine-pointer" | "always"`) — page-wise scroll, hidden where the rail cannot scroll, labelled via `labels`, mirrored in RTL, jump under reduced motion; no wheel scrolling, so arrows are the desktop path
  • RTL — `dir` prop or the nearest `[dir]` ancestor drives Embla direction; logical positions; mirrored fades
  • AddStoryThumbnail standalone sub-export — dashed-border placeholder + 50%-opacity user avatar + Plus badge
  • leading?: ReactNode slot — render any custom prefix (AddStoryThumbnail / Live indicator / Pinned callout / etc.)
  • Realtime via Subscribe<StoryRailDelta> contract — added / removed / viewed / updated; same shape as engagement-bar / comment-thread / post-card
  • onSubscribeDelta callback fires for every delta
  • Embla used inline (no wrapper hook, no cross-import) — align: 'start', containScroll: 'trimSnaps', dragFree: true (kasder-exact)
  • No indicator dots — story rails are skim-scroll, not snap carousels
  • Mode-aware, scroll-aware edge fades — from-card when framed, from-background when bare; shown only where the rail can scroll; width via `--story-rail-fade-width` (default 3rem)
  • Edge gradients render only when items present (not over empty state)
  • Click does NOT auto-mark-viewed — host owns viewing semantics via ref.current.markViewed(itemId)
  • renderThumbnail slot for full per-thumbnail takeover (themed rings, video previews, custom shapes)
  • Polymorphic linkComponent + getHref for navigation-mode (rare; thumbnails usually open modal viewer)
  • Imperative handle: scrollTo(itemIndex — `leading` not counted) / getCurrentItems / reset / dispatch / markViewed
  • storyRailReducer + useStoryRailState publicly exported (external state coordination)
  • Controlled or uncontrolled — `items` + `onItemsChange` (the prop wins every render; mutations and realtime deltas are reported) or `defaultItems`; `items` alone keeps the read-once behaviour with a dev warning
  • i18n via the labels object (rail, Add tile, arrows, empty state, thumbnailAriaLabel(item)) — `AddStoryThumbnail` reads the rail's labels from context; its own props still win
  • a11y — section role=region, button per thumbnail with descriptive aria-label, edge gradients aria-hidden
  • motion-safe:group-hover:scale-105 on thumbnails — reduced-motion users see static
  • Tailwind v4-clean (no legacy class names)
  • No new shadcn primitives — avatar already installed
  • No framer-motion — CSS transitions only

Tags

story-railsocialstoriesrailcarouselemblarealtimeinstagram

Dependencies

shadcn primitives: avatar
npm peer deps: embla-carousel-react@^8.6.0, lucide-react@^1.11.0