Story Composer
alphav0.6.1Instagram-style story creation surface — a locked 9:16 wrapper around the media editor.
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
pnpm dlx shadcn@latest initpnpm dlx shadcn@latest add @ilinxa/story-composerAdd -fixtures for dummy data:
pnpm dlx shadcn@latest add @ilinxa/story-composer-fixturesCLI 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
"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;
getErrorMessagesets 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