> ## Documentation Index
> Fetch the complete documentation index at: https://docs.embededitor.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Props

> Every prop EmbedEditor, mountEditor and openEditor take, with its type, its default and what it does.

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

> [!NOTE]
>
> 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](https://docs.embededitor.com/api-reference/errors.md).

## Source

**src** `string | File | Blob | ArrayBuffer | Uint8Array | HTMLImageElement | HTMLCanvasElement | ImageBitmap | null` (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.

**state** `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](https://docs.embededitor.com/api-reference/state.md) and [Pintura states](https://docs.embededitor.com/saving/pintura.md).

**enablePicker** `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

**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.

**closeOnEscape** `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

**aspectRatio** `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.

**aspectRatioLocked** `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

**enableAnnotate** `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.

**enableFilter** `boolean` (default: true)

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

**enableFinetune** `boolean` (default: true)

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

**enableObfuscate** `boolean` (default: true)

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

**enableResize** `boolean` (default: true)

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

**enableFrame** `boolean` (default: true)

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

## Output

**maxWidth** `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.

**maxHeight** `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.

**outputType** `'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.

**outputQuality** `number` (default: 90)

The JPEG and WebP quality, 0 to 100.

**enableCopy** `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.

**enableShare** `boolean` (default: false)

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

**watermark** `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](https://docs.embededitor.com/features/watermark.md).

**properties**

**text** `string`

The text, 1 to 80 characters, one line.

**src** `EmbedEditorMarkSource`

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

**lock** `'fixed' | 'required' | 'free'` (default: 'fixed')

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

**layout** `'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.

**size** `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).

**spacing** `number` (default: 50)

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

**angle** `number`

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

**opacity** `number` (default: 35)

10 to 100.

**color** `'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.

**font** `'inter' | 'montserrat' | 'oswald' | 'anton' | 'playfair-display' | 'courier-prime' | 'caveat' | 'pacifico' | 'permanent-marker'` (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.

**signature** `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.

**properties**

**text** `string`

The text, 1 to 80 characters.

**src** `EmbedEditorMarkSource`

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

**lock** `'fixed' | 'required' | 'free'` (default: 'free')

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

**position** `'auto' | 'top-left' | 'top' | 'top-right' | 'left' | 'center' | 'right' | 'bottom-left' | 'bottom' | 'bottom-right'` (default: 'bottom-right')

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

**size** `number`

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

**margin** `number` (default: 4)

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

**opacity** `number` (default: 100)

10 to 100.

**color** `'auto' | string` (default: 'auto')

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

**font** `'inter' | 'montserrat' | 'oswald' | 'anton' | 'playfair-display' | 'courier-prime' | 'caveat' | 'pacifico' | 'permanent-marker'` (default: 'inter')

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

**logo** `string`

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

**logoText** `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

**colors** `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](https://docs.embededitor.com/customization/theming.md).

**properties**

**accent** `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.

**controls** `string` (default: yellow)

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

**surface** `string` (default: zinc)

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

**annotationColor** `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.

**annotationTheme** `'light' | 'dark' | 'accent'` (default: 'light')

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

**lang** `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](https://docs.embededitor.com/customization/languages.md).

**properties**

**texts** `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.

**extend** `'en-us' | 'es-es' | 'pt-br'`

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

**locale** `string`

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

**displayBadge** `boolean` (default: true)

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

## Callbacks

**onLoad** `(\{ 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).

**onLoadError** `(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.

**onProcess** `(\{ 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.

**onProcessError** `(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.

**onClose** `() =\> 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.