Props

EmbedEditor takes these props, and so do mountEditor and openEditor (all but layout). Every prop is optional and applies live unless it says otherwise.

A value the editor can’t take, a misspelt prop or a removed one is INVALID_PROPS: the error screen names it and onLoadError hears it. See EmbedEditorError.

Source

default:"null"

The image, read at open: a URL (https:, http:, data: or blob:), a File or Blob, its bytes, an <img>, a canvas or an ImageBitmap.

A URL and an <img>’s currentSrc (or src) are downloaded with fetch: a cross-origin one needs CORS.
An ArrayBuffer or Uint8Array is read as the file’s bytes; a subarray gives just its own bytes.
null or absent opens the empty state, unless enablePicker is off.

While the empty state, a load or the error screen shows, a new src replaces the one opening. Once an image is on screen, a new src is ignored: to open another image, give the editor a new key in React, or destroy it and mount it again with mountEditor. Pass a stable value: a new object on every render restarts the load each time the host renders while the image loads.

EditState | PinturaState | null

default:"null"

The edits the image opens with, read at open like src: a state saved before, or one the legacy Pintura editor saved. A Pintura state opens with its crop, ratio, rotation, flips, output size and redactions; its filter, adjustments and frame are dropped. See EditState and Pintura states.

boolean

default:"true"

With no src, the editor asks for the image: a file chosen, dropped or pasted. Off, it shows its loading screen until a src comes.

Layout

'inline' | 'page'

default:"'inline'"

Where the editor sits: in the box the host gives it ('inline'), or over the whole viewport as the page itself ('page': the page behind doesn’t scroll, the safe areas are kept clear). Not on openEditor, which is its own layout.

boolean

default:"true"

Whether Escape closes the editor: the modal, or inline and page with onClose. Off, only the Close button and Save close it; Escape keeps its other jobs.

Crop

number | null

default:"null"

The ratio (width / height, above 0) the crop opens at: its largest window, on the photo’s subject. null: free. A saved edit given in state opens as it was saved unless the ratio is locked. Given live, it applies as one step undo can take back.

boolean

default:"false"

Fixes the ratio and hides the ratio selector. With no aspectRatio, the ratio the image opens with is kept. Given live, the locked ratio is where undo starts, so undo can’t free it.

`aspectRatio`	`aspectRatioLocked`	Opens with
a number	`true`	That ratio, even over a saved edit.
`null`	`true`	The ratio the opened state has: its own, or its crop’s shape.
a number	`false`	That ratio for a new edit. A saved edit opens as it was saved.
`null`	`false`	A free crop.

Tools

boolean

default:"true"

Full edition. The Annotate button, at the tool row’s right end, and its mode: arrows, texts, numbers, a ruler, shapes, drawing and a lens over the image. Turned off, the annotations already in the state are still drawn and saved.

boolean

default:"true"

Full edition. The Filter tool. Turned off, a filter already in the state stays and is saved.

boolean

default:"true"

Full edition. Auto and the adjustments. Turned off, their values in the state stay and are saved.

boolean

default:"true"

Full edition. The Obfuscate tool. Turned off, the areas already in the state stay and are saved.

boolean

default:"true"

Full edition. The Resize tool. Turned off, a size already in the state stays and is saved.

boolean

default:"true"

Full edition. The Frame tool. Turned off, a frame already in the state stays and is saved.

Output

number

The output’s largest width, in px (1 or more). Alone it caps the width; with maxHeight the output fits inside both. The ratio is kept and the image is never enlarged.

number

The output’s largest height, in px (1 or more). Alone it caps the height; with maxWidth the output fits inside both. The ratio is kept and the image is never enlarged.

'image/jpeg' | 'image/png' | 'image/webp'

default:"the source's"

The type Save and Share write: the source’s when it is one of these. A source of another type (HEIC, AVIF, GIF…) saves as PNG.

number

default:"90"

The JPEG and WebP quality, 0 to 100.

boolean

default:"false"

A Copy button left of Save: the image as Save makes it, on the clipboard as a PNG. Hidden where the browser can’t write an image there.

A Share button left of Save: the image as Save makes it, in the system share sheet. Shown only where the browser can share an image file.

Branding

EmbedEditorWatermark | null

default:"null"

Full edition. The host’s watermark over the photo. Give text or src, exactly one. Sizes are the mark’s height in % of the output’s shorter side. See Watermark and signature.

Show properties

string

The text, 1 to 80 characters, one line.

EmbedEditorMarkSource

The image, drawn as a silhouette in color: anything src takes, SVG included.

'fixed' | 'required' | 'free'

default:"'fixed'"

'fixed': shown, never touched. 'required': adjustable (a text’s font too), never removed. 'free': adjustable, text editable, removable.

'grid' | 'single'

default:"'grid'"

'grid': repeated over the whole photo. 'single': one mark in the center. The layout it opens in: unless it is fixed, the user can switch it.

number

The height in layout: 1 to 20 in a grid (default 4 for a text, 8 for an image), 4 to 60 single (default 12 for a text, 24 for an image).

number

default:"50"

The grid’s gap, 0 to 100, measured in the mark’s size.

number

Degrees, −90 to 90, in layout. Default −30 in a grid, 0 for a single mark.

number

default:"35"

10 to 100.

'auto' | string

default:"'auto'"

The color it opens in, of its text or its image’s silhouette: 'auto' (white or black, as the photo under it reads), or a hex, rgb(), hsl() or a CSS color name. The user changes it unless it is fixed.

default:"'inter'"

A text’s letter, by its slug: one of the nine Annotate offers. It is the one the mark opens in: the user picks another in its Font menu unless it is fixed. An image has none.

EmbedEditorSignature | null

default:"null"

Full edition. The host’s signature over the photo. Give text or src, exactly one. Sizes are the mark’s height in % of the output’s shorter side.

Show properties

string

The text, 1 to 80 characters.

EmbedEditorMarkSource

The logo: anything src takes, SVG included. It keeps its own colors.

'fixed' | 'required' | 'free'

default:"'free'"

'fixed': shown, never touched. 'required': adjustable (a text’s font too), never removed. 'free': adjustable, text editable, removable.

default:"'bottom-right'"

'auto' (the emptiest corner of the photo) or one of the 9 points.

number

The height, 2 to 40. Default 3.5 for a text, 14 for an image.

number

default:"4"

The distance to the edges at the 9 points, 0 to 20. The center ignores it.

number

default:"100"

10 to 100.

'auto' | string

default:"'auto'"

The text’s color it opens with, as the watermark’s. A logo keeps its own colors.

default:"'inter'"

A text’s letter, as the watermark’s.

string

The host’s logo, left of the toolbar: an http(s):, data: or blob: URL.

string

The host’s name as text, left of the toolbar: alone in the logo’s place, or after the logo image when both are given (an image that fails to load leaves the name alone). One line in the editor’s letters, cut with an ellipsis where it doesn’t fit.

Appearance

EmbedEditorColors

default:"yellow on zinc"

One base color per role, the only way to theme the editor. Each is the 500 of the scale the editor makes from it: a hex (#6366f1), rgb(), hsl() or a CSS color name. A role left out takes its default. See Theming.

Show properties

string

default:"yellow"

The host’s brand: the buttons that act (Save, Annotate’s button while on, Choose File), what the stage selects and snaps to, and the annotations’ Default color.

string

default:"yellow"

The value controls only: a positive value’s ring, the ruler’s needle, the tool marker, a slider’s handle.

string

default:"zinc"

The editor’s body: backgrounds, text, lines.

string

default:"the accent the editor paints"

Full edition. The color the annotations start with, drawn opaque: a hex, rgb(), hsl() or a CSS color name.

'light' | 'dark' | 'accent'

default:"'light'"

Full edition. What sits behind the annotations’ labels at first: light, dark, or their color.

Lang | { extend?: Lang; locale?: string; texts: LangTexts }

default:"'en-us'"

The language: a built-in code ('en-us', 'es-es', 'pt-br'; any other string reads as 'en-us'), or your own texts, over a built-in language or a new one. See Languages.

Show properties

LangTexts

required

Any subset of the editor’s messages, by key, each one a string. A message with { name } placeholders keeps exactly the placeholders of the English one, in any order.

'en-us' | 'es-es' | 'pt-br'

The built-in language the messages you leave out read. Without it, they read English.

string

A BCP 47 tag that formats the numbers, through Intl.NumberFormat. Default: the extend language, else 'en-us'.

boolean

default:"true"

Shows the output size over the top right of the image for a moment after it changes.

Callbacks

({ file, size }: { file: File | null; size: Size }) => void

Called once per open, when the image is on screen. file is the file it came from, at its own size (null for a canvas or an ImageBitmap). size is the size in px the editor works the image at: its own size up to 16.7 MP, the working copy’s past it (48 MP → 4729 × 3547).

(error: EmbedEditorError) => void

Called when the image can’t be opened or drawn, a prop is invalid (INVALID_PROPS), or a watermark’s or signature’s image or letter can’t load (MARK_FAILED). The error screen shows it too.

({ dest, state }: { dest: File; state: EditState }) => void

Called with what Save made (dest) and the state it was made with. Without it, Save downloads the file. If it throws, the error is logged with console.error, Save shows it failed and the modal stays open; onProcessError isn’t called.

(error: EmbedEditorError) => void

Called when Save can’t make the file (EXPORT_FAILED) or can’t draw a fixed or required mark (MARK_FAILED). The banner over the toolbar says so too.

() => void

Called when the editor closes. On EmbedEditor and mountEditor, the Close button shows only with it.

If onLoad, onLoadError or onProcessError throws, the error is logged with console.error and the editor carries on. It isn’t rethrown, so your error boundary won’t see it.

Overview

Entry Points

Commands

Reference

Source

Layout

Crop

Tools

Output

Branding

Appearance

Callbacks

​Source

​Layout

​Crop

​Tools

​Output

​Branding

​Appearance

​Callbacks

Source

Layout

Crop

Tools

Output

Branding

Appearance

Callbacks