Media Editor

When to use

MediaEditor is the reusable capture + edit surface underneath StoryComposer. Reach for it directly when you need an Instagram-style editor for a non-story context — a CMS hero re-edit, a chat attachment editor, the second step of a multi-step content composer. Four capability dials (enabledModes / enabledTools / mediaSources / aspect) plus inline/dialog presentation let you pull as little or as much editor surface as your context needs. Story-composer-01 is a thin wrapper around this in v0.2.0.

Quick start

import { useRef, useState } from "react"
import { MediaEditor, type MediaEditorHandle } from "@/components/media-editor"

export function Example() {
  const editorRef = useRef<MediaEditorHandle>(null)
  const [open, setOpen] = useState(false)

  return (
    <>
      <button onClick={() => setOpen(true)}>Edit photo</button>
      <MediaEditor
        ref={editorRef}
        aspect="9:16"
        presentation="dialog"
        isOpen={open}
        onClose={() => setOpen(false)}
        enabledModes={["photo", "video"]}
      />
    </>
  )
}

Capability dials

Four orthogonal props that gate the editor surface. Defaults are the maximal configuration.

• enabledModes — array of "photo" / "video" / "text". Empty array = no capture surface (pure-edit; pair with initialSource).
• enabledTools — array of "text" / "draw" / "stickers" / "filters" / "adjust" / "crop". Filters the toolbar and skips the corresponding layer at export.
• mediaSources — array of "camera" / "upload". Without camera (or with camera but no capture extension — see below) you get the file/ gallery intake surface.
• aspect — "9:16" / "1:1" / "16:9" / "4:5" / "free". Locks the canvas aspect ratio and the default crop choice.

Camera capture (opt-in slice)

Camera capture (getUserMedia + MediaRecorder, permission flows, shutter, multi-instance guard) ships as a separate registry item — @ilinxa/media-editor-capture — not part of the base install. Install it and pass its export through the capture prop:

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

<MediaEditor mediaSources={["camera", "upload"]} capture={mediaCapture} />

Without it, "camera" in mediaSources falls back to the base file/gallery intake surface (a button + hidden file input) — one dev console.warnfires, and the editor stays fully usable: pick a file → edit → export. Base-alone never pulls konva/ react-konva-adjacent camera weight it doesn't need.

Initial source (CMS re-edit / draft restore)

Pass initialSource to skip the capture surface and land directly in the edit canvas with the source pre-loaded. Three accepted shapes:

• { kind: "url", url, mode } — editor fetch()es the URL. Same-origin or CORS-friendly only; CORS failure surfaces via onInitialSourceError as { kind: "cors" }.
• { kind: "blob", blob, mode } — consumer-owned blob. Escape hatch for non-CORS URLs (pre-fetch on the server, pass the Blob through).
• { kind: "file", file } — mode auto-detected from file.type (image/* → photo, video/* → video; anything else fires { kind: "unsupported-file-type" }).

The resolved mode must be a member of enabledModes; a mismatch fires { kind: "mode-not-enabled" }.

Presentation: inline / dialog / auto

inline renders bare in the parent layout — used by step-2-of-multi-step composers and CMS hero editors. dialog wraps in shadcn dialog (mobile-fullscreen / desktop-modal sized by aspect) — used by story-composer, chat-panel.

auto picks inline when enabledModes is empty (pure-edit context, no capture chrome to manage), otherwise dialog. Dialog mode requires isOpen + onClose — a dev-only console.error fires if either is missing.

Export

Call the imperative handle from your publish flow. Each method returns { blob, metadata }.

// Photo / text-mode → image. Default: image/jpeg, quality 0.9.
const { blob, metadata } = await editorRef.current.exportImage({
  format: "image/jpeg",        // or "image/png" | "image/webp"
  quality: 0.9,
  onProgress: (p) => …,        // fires (0) at start, (1) on completion
})

// Video — perf-shortcut returns the raw blob when no overlays have
// been added; otherwise re-encodes through MediaRecorder with the
// Konva overlay baked in per frame.
const out = await editorRef.current.exportVideo({
  onProgress: (p) => …,        // ~10 ticks across the re-encode
})

// Polymorphic — dispatches on the current mode.
const out = await editorRef.current.export()

Imperative handle

22 methods total — inspect (getIsDirty, getMode, getState, loadState), capture (switchCamera, takePhoto, startRecording, stopRecording, importFromGallery), edit (addText, addSticker, setAdjustments, applyFilter, clearLayer, undo, redo), export (exportImage, exportVideo, export), and lifecycle (reset, open, close).

More

Full reference, the capture-vs-edit chrome model, pan & zoom gestures, accessibility notes, and integration patterns live in docs/procomps/media-editor-procomp/media-editor-procomp-guide.md.