API Reference

Complete props reference for the ImageEditor and ImageEditorModal components. For the config object, see Configuration.

ImageEditor

The main editor component. Renders inline at the given dimensions.

Prop	Type	Default	Description
`src`	`string \| File \| Blob \| HTMLImageElement \| HTMLCanvasElement`	—	Required. Image source.
`onSave`	`(blob: Blob) => void`	—	Called when the user exports the image.
`onClose`	`(reason?: CloseReason, hasUnsavedChanges?: boolean) => void`	—	Called when the editor closes.
`onReady`	`(handle: EditorHandle) => void`	—	Fires once when the engine is ready, exposing an imperative handle.
`width`	`string \| number`	`"100%"`	Editor width.
`height`	`string \| number`	`"100vh"`	Editor height.
`config`	`ImageEditorConfig`	`{}`	Editor configuration.
`slots`	`EditorSlots`	—	Custom UI slots.
`events`	`EditorEventCallbacks`	—	Event callbacks.
`validation`	`ImageValidationOptions`	—	File validation rules.
`keepZoomOnSourceChange`	`boolean`	`false`	Preserve zoom/pan when `src` changes.

CloseReason is one of "save", "close-button", "back-button", or "escape".

Wraps ImageEditor in a Radix Dialog for modal usage. Accepts all ImageEditor props, plus:

Prop	Type	Default	Description
`open`	`boolean`	—	Required. Control modal visibility.
`onOpenChange`	`(open: boolean) => void`	—	Called when visibility changes.
`className`	`string`	—	Class for the dialog content wrapper.
`overlayClassName`	`string`	—	Class for the overlay.

Inject custom UI into the editor shell. See Inject Custom UI.

Slot	Type	Description
`topbarRight`	`ReactNode`	Right side of the top bar (before export).
`sidebarBottom`	`ReactNode`	Bottom of the tool sidebar (above Apps).
`contextualBarExtra`	`ReactNode`	Extra content in the contextual bar.

React to editor lifecycle events. See React to Editor Events.

Callback	Type	Description
`onToolChange`	`(toolId: string \| null) => void`	Fires when the active tool changes.
`onBeforeSave`	`(blob: Blob) => Promise<Blob \| undefined> \| Blob \| undefined`	Transform the export blob before save.

Reject or warn on unsuitable source files.

Option	Type	Default	Description
`acceptedFormats`	`string[]`	common image types	Accepted MIME types.
`maxFileSize`	`number`	`50 MB`	Reject files larger than this (bytes).
`warnFileSize`	`number`	`20 MB`	Warn above this size (bytes).
`maxDimension`	`number`	`16000`	Reject images wider/taller than this (px).
`warnDimension`	`number`	`8000`	Warn above this dimension (px).