Skip to content
ilinxa/pro-ui

Story Composer

alphav0.6.1

Instagram-style story creation surface — a locked 9:16 wrapper around the media editor.

Category: MediaUpdated: 2026-10-25Created: 2026-05-31Author: ilinxa

Context

Third component in the story-system trilogy alongside story-rail (discovery) and story-viewer (consumption). It wraps @ilinxa/media-editor (requires 0.6.0+) for the capture + edit surface and layers the story publish flow on top: ComposerPublishBar in the renderTopBar slot, an optional details step (caption + host fields), and the progress / error overlay — both rendered through the editor's overlay prop, with the editor body inert behind them. The default install is upload-only; camera capture is opt-in by passing capture={mediaCapture} from @ilinxa/media-editor-capture, which keeps camera capture and recording out of the default install. Konva stays with the editor.

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-composer

Add -fixtures for dummy data:

pnpm dlx shadcn@latest add @ilinxa/story-composer-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

All three modes (photo / video / text), 36 built-in emoji stickers. Wired to a fake uploader for the docs site — consumers pass `uploadUrl` or a real `uploader` for prod.

Demo source

demo.tsxtsx
"use client"; import { useEffect, 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 { StoryComposer } from "./story-composer";import { SAMPLE_BRAND_STICKERS } from "./dummy-data";import type { PublishedStory, StoryComposerLabels } from "./types"; /** * A complete Arabic label set: every story-composer key plus the nested * media-editor labels, so nothing in the RTL tab falls back to English. */const AR_LABELS: StoryComposerLabels = {  composerLabel: "إنشاء قصة",  composerDescription:    "أنشئ قصة جديدة بالتقاط صورة أو تسجيل فيديو أو كتابة نص فقط. اضغط زر الإغلاق للخروج.",  modePhoto: "صورة",  modeVideo: "فيديو",  modeText: "نص",  shutterPhoto: "التقاط صورة",  shutterVideoStart: "بدء التسجيل",  shutterVideoStop: "إيقاف التسجيل",  galleryPicker: "اختيار من المعرض",  switchCamera: "تبديل الكاميرا",  permissionDeniedTitle: "الوصول إلى الكاميرا محظور",  permissionDeniedBody:    "نحتاج إلى إذن الكاميرا لالتقاط قصتك. فعّله من إعدادات المتصفح أو اختر ملفًا من المعرض.",  permissionRetry: "حاول مرة أخرى",  permissionUsePicker: "استخدم المعرض بدلًا من ذلك",  permissionRequesting: "جارٍ طلب الكاميرا…",  toolText: "نص",  toolDraw: "رسم",  toolStickers: "ملصقات",  toolFilters: "فلاتر",  toolAdjust: "ضبط",  toolCrop: "اقتصاص",  adjustBrightness: "السطوع",  adjustContrast: "التباين",  adjustSaturation: "التشبع",  adjustBlur: "التمويه",  drawColor: "اللون",  drawBrush: "حجم الفرشاة",  drawEraser: "ممحاة",  textPlaceholder: "اكتب شيئًا…",  textFontFamily: "الخط",  textFontSize: "الحجم",  publish: "نشر",  publishing: "جارٍ النشر…",  published: "تم النشر",  close: "إغلاق",  discardConfirmTitle: "تجاهل القصة؟",  discardConfirmBody: "ستفقد الوسائط التي التقطتها وتعديلاتك. لا يمكن التراجع عن ذلك.",  discardConfirm: "تجاهل",  discardCancel: "متابعة التعديل",  uploadFailedTitle: "فشل الرفع",  uploadFailedBody: "حدث خطأ أثناء النشر. قصتك ما زالت هنا.",  uploadRetry: "حاول مرة أخرى",  uploadCancel: "إلغاء",  uploadErrorNoDestination: "مرّر uploadUrl أو uploader للنشر.",  uploadErrorHttp: (status) => `فشل الرفع (HTTP ${status})`,  uploadErrorNetwork: "خطأ في شبكة الرفع",  uploadErrorBadResponse: "استجابة الرفع ليست JSON",  uploadCancelled: "تم إلغاء الرفع",  detailsTitle: "أضف التفاصيل",  detailsBack: "رجوع",  captionLabel: "التعليق",  captionPlaceholder: "اكتب تعليقًا…",  captionCounter: (count, max) => `${count} / ${max}`,  captionRequired: "أضف تعليقًا للنشر",  captionTooLong: (max) => `التعليق طويل جدًا (الحد الأقصى ${max})`,  recordingLabel: "جارٍ التسجيل",  editor: {    shell: {      title: "محرر الوسائط",      description: "التقط صورة أو سجّل فيديو أو اكتب نصًا فقط.",      back: "رجوع",      apply: "تطبيق",      cancel: "إلغاء",      backToCapture: "العودة إلى الالتقاط",      editTools: "أدوات التعديل",    },    capture: {      requestingCamera: "جارٍ طلب الكاميرا…",      cameraIdle: {        title: "الكاميرا جاهزة",        body: "اضغط أدناه لتفعيل الكاميرا أو اختر ملفًا من المعرض.",        enableCta: "تفعيل الكاميرا",      },      cameraDenied: {        title: "الوصول إلى الكاميرا محظور",        body: "نحتاج إلى إذن الكاميرا. فعّله من إعدادات المتصفح أو اختر ملفًا من المعرض.",        retryCta: "حاول مرة أخرى",        useGalleryCta: "استخدم المعرض بدلًا من ذلك",      },      noCameraTitle: "لا توجد كاميرا متاحة",      cameraErrorTitle: "الكاميرا غير متاحة",      galleryButton: "اختيار من المعرض",      switchCamera: "تبديل الكاميرا",      modes: { photo: "صورة", video: "فيديو", text: "نص" },      shutter: {        photo: "التقاط صورة",        videoStart: "بدء التسجيل",        videoStop: "إيقاف التسجيل",      },      recording: "جارٍ التسجيل",      connectCta: "الاتصال بالكاميرا",      connectHint: "اختر وضعًا من الأعلى أو انتقل مباشرة إلى الكاميرا.",      errors: {        videoUnsupported: "تسجيل الفيديو غير مدعوم هنا",        videoFailed: "فشل تسجيل الفيديو",        videoCodecUnavailable: "لا يمكن تسجيل أي من صيغ الفيديو المسموح بها في هذا المتصفح",      },    },    toolbar: {      text: "نص",      draw: "رسم",      stickers: "ملصقات",      filters: "فلاتر",      adjust: "ضبط",      crop: "اقتصاص",    },    adjust: { brightness: "السطوع", contrast: "التباين", saturation: "التشبع", blur: "التمويه" },    draw: { color: "اللون", brushSize: "حجم الفرشاة", eraser: "ممحاة" },    text: {      placeholder: "اكتب شيئًا…",      fontFamily: "الخط",      fontSize: "الحجم",      alignLeft: "محاذاة لليسار",      alignCenter: "توسيط",      alignRight: "محاذاة لليمين",      delete: "حذف النص",      background: "الخلفية",    },    color: { hex: "Hex", swatch: (color) => `اللون ${color}` },    crop: { free: "حر", aspectCount: (_count, formatted) => `(${formatted} نسب اقتصاص)` },    canvas: {      label: "لوحة محرر الوسائط — الأسهم للتحريك، +/- للتكبير، 0 للإعادة",      resetZoom: "إعادة التكبير",      resizeHandle: (corner) => `تغيير الحجم ${corner}`,    },    discard: {      title: "تجاهل؟",      body: "ستفقد الوسائط التي التقطتها وتعديلاتك.",      cancel: "متابعة التعديل",      confirm: "تجاهل",    },    intake: {      prompt: "اختر صورة أو فيديو من جهازك.",      unknownType: "غير معروف",      unsupportedType: (fileType) => `نوع الملف غير مدعوم: ${fileType}`,      fileTooLarge: (_sizeMb, _maxMb, sizeFormatted, maxFormatted) =>        `حجم الملف ${sizeFormatted} م.ب — الحد الأقصى ${maxFormatted} م.ب`,    },    empty: {      noSource: "لم يتم تقديم مصدر",      noSourceHint: "مرّر initialSource أو فعّل وضع التقاط في enabledModes.",      noSourceAria: "محرر الوسائط: لم يتم تقديم مصدر. مرّر initialSource أو فعّل وضع التقاط.",      loadFailed: "تعذر تحميل المصدر",      attempted: "المحاولة",      enabled: "مفعّل",      type: "النوع",      blank: "(فارغ)",      none: "(لا شيء)",      noCaptureSource: "لا يوجد مصدر التقاط متاح",      aspect: "النسبة:",      sources: "المصادر:",    },  },}; // Demo-site uploader — pretends to upload (1.5s) and returns the blob's own// object URL. Keeps every tab able to round-trip Publish → Done without a// real backend; consumers wire `uploadUrl` or their own `uploader` for prod.async function demoUploader(blob: Blob) {  await new Promise((r) => setTimeout(r, 1500));  return {    url: URL.createObjectURL(blob),    thumbnailUrl: URL.createObjectURL(blob),  };} export default function StoryComposerDemo() {  return (    <Tabs defaultValue="default" className="flex flex-col gap-4">      <SwipeTabsList>        <TabsTrigger value="default">Default</TabsTrigger>        <TabsTrigger value="photo-only">Photo only</TabsTrigger>        <TabsTrigger value="custom-stickers">Custom stickers</TabsTrigger>        <TabsTrigger value="custom-uploader">Custom uploader</TabsTrigger>        <TabsTrigger value="no-confirm">No discard guard</TabsTrigger>        <TabsTrigger value="caption">Caption step</TabsTrigger>        <TabsTrigger value="rtl">RTL</TabsTrigger>      </SwipeTabsList>       <TabsContent value="default">        <ComposerLauncher          description="All three modes (photo / video / text), 36 built-in emoji stickers. Wired to a fake uploader for the docs site — consumers pass `uploadUrl` or a real `uploader` for prod."          props={{ uploader: demoUploader }}        />      </TabsContent>       <TabsContent value="photo-only">        <ComposerLauncher          description="hideModes={['video','text']} — photo-only flow (useful for product or content surfaces that don't accept video)."          props={{            uploader: demoUploader,            hideModes: ["video", "text"],          }}        />      </TabsContent>       <TabsContent value="custom-stickers">        <ComposerLauncher          description="Adds a consumer-supplied sticker set (Ilinxa brand) alongside the built-in catalog. Toggle replaceBuiltinStickers to ship consumer-only."          props={{            uploader: demoUploader,            stickers: [SAMPLE_BRAND_STICKERS],          }}        />      </TabsContent>       <TabsContent value="custom-uploader">        <ComposerLauncher          description="Custom async uploader — useful for S3 pre-signed PUT, Cloudinary direct upload, Mux. The composer hands the blob + metadata to your function and you return { url }."          props={{ uploader: demoUploader }}        />      </TabsContent>       <TabsContent value="no-confirm">        <ComposerLauncher          description="confirmOnDiscard={false} — silent discard on close, matching Instagram's behavior. Don't ship this in production unless you have a separate draft-recovery path."          props={{ uploader: demoUploader, confirmOnDiscard: false }}        />      </TabsContent>       <TabsContent value="caption">        <ComposerLauncher          description="caption={{ maxLength: 120, required: true }} — Publish opens a details step (caption + counter, Back / Publish). Upload-only: no camera tab unless you pass capture={mediaCapture}."          props={{            uploader: demoUploader,            caption: { maxLength: 120, required: true },          }}        />      </TabsContent>       <TabsContent value="rtl">        <div dir="rtl" lang="ar">          <ComposerLauncher            rtl            description="dir=rtl — the document direction flips while the composer is open; labels are Arabic. The publish bar and details step use logical (start / end) positioning."            props={{              uploader: demoUploader,              caption: { maxLength: 120 },              locale: "ar",              labels: AR_LABELS,            }}          />        </div>      </TabsContent>    </Tabs>  );} interface ComposerLauncherProps {  description: string;  props: Partial<React.ComponentProps<typeof StoryComposer>>;  /** Flip the document direction to rtl while the composer is open (portal content). */  rtl?: boolean;} function ComposerLauncher({ description, props, rtl }: ComposerLauncherProps) {  const [open, setOpen] = useState(false);   // The composer renders in a portal outside any local dir="rtl" wrapper.  useEffect(() => {    if (!rtl || !open) return;    const root = document.documentElement;    const prev = root.dir;    root.dir = "rtl";    return () => {      root.dir = prev;    };  }, [rtl, open]);   const [lastPublished, setLastPublished] = useState<PublishedStory | null>(    null,  );   return (    <div className="flex flex-col items-center gap-4 p-8">      <p className="max-w-md text-center text-sm text-muted-foreground">        {description}      </p>      <Button onClick={() => setOpen(true)}>Open composer</Button>      <StoryComposer        isOpen={open}        onClose={() => setOpen(false)}        onPublished={(story) => {          setLastPublished(story);          setOpen(false);        }}        {...props}      />      {lastPublished ? (        <pre className="max-w-md overflow-x-auto rounded-md border border-border bg-muted p-3 font-mono text-xs">          {JSON.stringify(lastPublished, null, 2)}        </pre>      ) : null}    </div>  );} 

Usage

When to use

StoryComposer is the creation surface for Instagram-style stories: pick (or capture) media, edit it on a 9:16 canvas, publish. It composes with StoryRail (discovery) and StoryViewer(consumption) but doesn't depend on them. It wraps MediaEditor.

Quick start

import { useState } from "react"
import { StoryComposer } from "@/components/story-composer"

export function Example() {
  const [open, setOpen] = useState(false)

  return (
    <>
      <button onClick={() => setOpen(true)}>Create story</button>
      <StoryComposer
        isOpen={open}
        onClose={() => setOpen(false)}
        uploadUrl="/api/stories/upload"
        onPublished={(story, result) => {
          // result = exactly what your upload returned
          setOpen(false)
        }}
      />
    </>
  )
}

Camera (opt-in)

The default install is upload-only — no camera code and no getUserMedia. To add the camera, install @ilinxa/media-editor-capture and pass it in:

import { mediaCapture } from "@/components/media-editor/features/capture"

<StoryComposer capture={mediaCapture} … />

acceptMediaTypes limits what can be picked; videoOutput={{ mimeTypes: ["video/mp4"] }} limits what is recorded or re-encoded. An unedited video is uploaded as the original file.

Modes and tools

  • Photo / Video — pick (or capture) then edit with Text / Draw / Stickers / Filters / Adjust. Crop is opt-in via enabledTools. Videos are not edited: a video draft has no tool chips and uploads as the original file.
  • Text — gradient background + centred text; PNG on publish.

Hide modes with hideModes={["video","text"]}.

Publish

  • uploadUrl — POSTs FormData (file, metadata, uploadFields, caption and your fields) with progress.
  • uploader={async (blob, meta, fields) => …} — your own upload (signed URLs etc.); return at least { url }.
  • caption / renderPublishFields — Publish opens a details step first; canPublish(fields) gates it.
  • On failure: Retry, or Cancel back to the editor with the draft intact; getErrorMessage sets the message.

Imperative handle

publish, exportBlob, reset, close, addText, addSticker, setAdjustments, applyFilter. The capture methods and open are not implemented (they warn in development) — use isOpen and the in-UI controls.

More

Full reference, labels, and the 0.5 → 0.6 migration table live in docs/procomps/story-composer-procomp/story-composer-procomp-guide.md.

Features

  • v0.6.1 — a mode switch keeps media-editor's modified flag, so Cancel after an edit still asks to discard (media-editor 0.6.0 `loadState(…, { keepModified })`)
  • v0.6.0 — **breaking:** camera opt-in — the default install is upload-only and no longer depends on `@ilinxa/media-editor-capture`; pass `capture={mediaCapture}` to add it (`sources` defaults follow). `acceptMediaTypes` and `videoOutput` (e.g. MP4 only) are forwarded to media-editor. Details step: `caption` (`maxLength`, `required`), `renderPublishFields`, controlled `publishFields` / `onPublishFieldsChange`, `canPublish(fields)`; the uploader receives the fields as a third argument and the default upload adds them to its FormData. Error state: Cancel keeps the draft, `getErrorMessage`, localized uploader errors, `renderPublishingOverlay` gets `status` / `error` / `retry` / `cancel`. `onPublished(story, result)` passes the uploader's result untouched; a successful publish consumes the draft (the editor resets); one publish at a time, and close / `reset()` / Cancel cancel it; `publish()` opens the details step when one is configured; `ctx.openDetails`; Escape in the details step is Back and never closes the dialog. `labels.editor` takes media-editor's nested labels (no cast); `locale`; `labels.published` is announced. Overlay colours use `--media-overlay` tokens. Removed: the stale compat re-exports (ComposerCamera / ComposerEditor / ComposerToolbar / ColorSwatchPicker and the lib / default-token / crop helpers — import them from media-editor) and the never-rendered `drawUndo` / `drawRedo` / `textAlign` label keys
  • v0.5.0 — the publishing overlay (default and `renderPublishingOverlay`) renders inside media-editor's dialog via its `overlay` prop, so Retry / Cancel are clickable
  • v0.4.1 — `editorBackground` is marked @notImplemented and dev-warns; it was declared and never applied
  • Photo, video and text-only modes; file upload by default, camera (photo + video recording) with the capture add-on
  • Multi-layer Konva editor: image / drawing / stickers / text
  • Edit tools — Text, Draw (with eraser), Stickers (built-in emoji + your own), Filters (built-in presets with thumbnails), Adjust (brightness / contrast / saturation / blur), and opt-in Crop. Default `enabledTools` ships the first five
  • Pan + zoom on the editor canvas (1×–4×): drag to pan (yields to draggable overlays), two-finger pinch, wheel anchored to the cursor, arrow keys, +/-/0
  • Video: picked or recorded videos are uploaded as the original file — no tool edits video (the tool chips are hidden for video drafts)
  • Built-in upload via XHR POST FormData with progress, plus an `uploader` escape hatch for signed-URL flows
  • Responsive: mobile full-screen / desktop 9:16 modal, safe-area aware; top bar follows the IG chrome model
  • Discard-confirm guard for unsaved edits (opt-out via confirmOnDiscard: false)
  • Exported parts: ComposerPublishBar, PublishDetailsStep; hooks: useStoryComposerState, useImageUploader
  • Imperative handle: publish / exportBlob / reset / close and the editor's edit methods (addText, addSticker, setAdjustments, applyFilter); the capture methods and open forward to the editor, where they are not implemented

Tags

story-composerstoriescameraimage-editorvideokonvasocialpublish

Dependencies

shadcn primitives: button, textarea
npm peer deps: lucide-react@^1.11.0
internal: media-editor