Options
Every option the image editor accepts.
Every option of the image editor. In React, options are props of ImageEditor. With the custom element and mountImageEditor, they are keys of the options object. The type is ImageEditorProps, exported from @layermetry/media-editor/react.
Address security
Use HTTPS for every server and remote media address you pass to the editor. The only HTTP exceptions are http://localhost, http://127.0.0.1 and http://[::1], for development on your own computer. Relative paths and storage keys must resolve to an HTTPS address outside local development.
Hosted requests that carry your license key, including hosted captions, are refused over HTTP to another computer. For other addresses, HTTPS is the integration rule; the SDK does not enforce it on every option.
This rule also applies to addresses in templates, stock results and callback requests. The former proxyUrl option follows the same rule; use endpointUrl in new integrations.
Custom actions
| Name | Type | Default | Description |
|---|---|---|---|
customActions | Read-only ImageCustomAction[] | None | Adds host buttons to the selection controls and right-click menu. See Custom actions. |
onCustomAction | (event: ImageCustomActionEvent) => void | None | Receives started and a final run status. |
Required
| Name | Type | Default | Description |
|---|---|---|---|
licenseKey | string | none | Your license key. See License keys. |
onClose | () => void | none | Called when the user closes the editor, and after Save & Exit and Share. |
Size and layout
| Name | Type | Default | Description |
|---|---|---|---|
width | number | string | '100%' | The width of the editor. A number is in pixels. In React, the width of the box that the component renders. |
height | number | string | '100%' | The height of the editor. A number is in pixels. In React, the height of the box that the component renders. |
Look
| Name | Type | Default | Description |
|---|---|---|---|
theme | Partial<Record<ImageSemanticRole, string>> | Layermetry palette | Colors of the editor, by role. See Colors. |
darkMode | boolean | false | Uses the dark palette. |
typography | { heading, body, mono } | editor fonts | CSS font families for the editor's buttons and panels. |
radii | { sm, md, lg, full } | editor rounding | CSS corner sizes for the editor's buttons and panels. |
logo | string | none | The address of your logo, shown in the top bar. Use HTTPS for the logo address. |
showThemeCreator | boolean | false | true shows the button that opens the Customization Studio. Any other value hides it. See Editor settings. |
icons | Icon-name map | Built-in icons | Accepts IconData or React components; see Editor settings. |
ui | ImageUiConfig | all tools | The order, names, and visibility of tools and AI controls. See UI customization. |
ui.selection | ItemListConfig | The default lists | Hides, orders, labels and chooses display for the controls of the selected item. Applied after the default lists, on the desktop bar and on the phone. |
ui.toolbar | ItemListConfig | None | Older setting for toolbar groups. Its group ids are translated into control ids, with one console warning. Use ui.selection instead. |
ui.customActions.shown | CustomActionsUiConfig["shown"] | Surface counts | Sets custom-action overflow counts within their maximums. |
Content and services
| Name | Type | Default | Description |
|---|---|---|---|
stockMediaApis | StockMediaConfig | none | Pexels and Unsplash. See Stock media. Use HTTPS for provider endpoints and returned media addresses. |
stickers | StickerConfig | built-in stickers | Sticker sources. { sources: [] } removes the Stickers tool. See Stickers and GIFs. Use HTTPS for remote source and sticker addresses. |
googleFonts | { hosted: true } | { endpointUrl } | { requestFn } | Built-in families | Where the font panel gets the whole Google Fonts catalog. See Fonts. Use HTTPS for a custom endpoint. |
googleFontsApiKey | string | none | Deprecated. Sends your Google key from the browser. Use googleFonts. |
mediaApiUrl | string | none | Your media server, for background removal. Use HTTPS. |
files | File | none | A picture that the editor places on the page when it starts. |
createAutomatedContent | ({ query, contentType, metadata }) => Promise<{ success?, error? }> | none | Your own text generator, behind a Generate tool. Answer { success: { type: 'text', content: string[] } }, and each line the user ticks becomes a text box. |
showAttributionOverlay | boolean | false | The starting value of Show photo credits on the canvas in the Export panel. |
includeAttributionInExport | boolean | false | The starting value of Include photo credits in the export. |
AI
Configure generation through ai; expose developer tests separately with showAiPlayground.
| Name | Type | Default | Description |
|---|---|---|---|
ai | EditorAIConfig | None | Configures transport, operations and hooks. |
ai.endpointUrl | string | None | Sends requests to your server without the SDK license header. Use HTTPS. |
ai.requestFn | AIRequestFunction | None | Passes a request and AbortSignal to your callback. Use HTTPS for requests made by your callback. |
ai.hosted | true | None | Coming soon. Available only with an enterprise licence from Layermetry. Use your own endpointUrl or requestFn. |
ai.headers | AIHeaderValues or AIHeadersFunction | None | Supplies same-origin endpoint headers before each attempt. |
ai.credentials | omit, same-origin or include | same-origin | Sets endpoint request cookie behavior. |
ai.timeoutMs | number | None | Limits submission time with your endpoint or function. |
ai.maxRetries | number | 0 | Sets extra endpoint attempts with an idempotency header. |
ai.idempotencyKeyHeader | string | None | Names the server header used with positive maxRetries. |
ai.brand | false or { addToPrompt?, operations? } | Brand on | Controls the Use brand switch in the Generate boxes. false removes it. See Brand kits. |
ai.limits | { maxPerSession?: number } | Unlimited | Caps attempts across operations in a session. |
ai.text | Boolean or operation options | Enabled with usable AI | Configures text independently. |
ai.textRewrite | Boolean or operation options | Enabled with usable AI | Configures textRewrite independently. |
ai.image | Boolean or operation options | Enabled with usable AI | Configures image independently. |
ai.imageEdit | Boolean or operation options | Enabled with usable AI | Configures imageEdit independently. |
ai.sticker | Boolean or operation options | Enabled with usable AI | Configures sticker independently. |
ai.svgPath | Boolean or operation options | Enabled with usable AI | Configures svgPath independently. |
ai.onGenerationError | AIGenerationErrorObserver | None | Observes one failure per attempt. |
ai.onGenerationEvent | AIGenerationEventObserver | None | Observes generation lifecycle events. |
ai.errorMessages | AIErrorWordingByCategory | SDK wording | Replaces error wording by category. |
ai.supportUrl | HTTPS string | None | Adds Contact support on account and transport failures. Use HTTPS. |
showAiPlayground | boolean | false | Adds AI testing to the developer Studio. |
templateGeneration | TemplateGenerationConfig | None | Configures generation of complete templates through a separate callback. |
Choose exactly one transport. headers, credentials and retries require endpointUrl. With requestFn, only timeoutMs is accepted. The former proxyUrl name is not supported.
Operations share models, defaultModel, providers, transport and maxPerSession. Choose either models or providers. See AI providers for defaults, fields and restrictions.
Templates and storage
| Name | Type | Default | Description |
|---|---|---|---|
onGetTemplates | (filter?) => Promise<Template[]> | none | Lists the templates for the Templates panel. Use HTTPS for remote media addresses in returned templates. |
filter | any | none | A value that the editor passes to onGetTemplates. |
onSaveTemplate | (props) => Promise<void> | none | Saves a template or a draft. Without it, no save button appears. |
defaultTemplate | Template | none | A template on the page when the editor starts. Use HTTPS for remote media addresses in the template. |
templateCanvasPolicy | 'adopt' | 'fit' | 'place' | 'adopt' | What happens when a template has another page size. |
mediaAddPolicy | 'fit' | 'fill' | 'none' | 'fit' | Placement of new pictures: fit inside, cover the page, or use native pixels centered. Any other value is treated as 'fit', with one console warning. |
templateMetadata | metadataWithContext | none | Your fields for saved templates (metadata), and your brand: brands and activeBrandId, or the one-brand colors, textStyles, and logoUrl. See Brand kits. Use HTTPS for remote brand logo addresses. |
onBrandChange | (brandId: string) => void | none | Called with the id of the active brand kit when the editor opens and on every switch. See Brand kits. |
onUploadAsset | UploadAssetHandler | none | Stores a picture in your storage, and returns its address. Return an HTTPS address, or a storage key that resolves to one. |
resolveAssetUrl | ResolveAssetUrl | none | Turns a stored value into an address that the browser can load. Resolve remote media to HTTPS. |
assetBaseUrl | string | none | The address that stored paths are added to. Use an HTTPS base address. |
assetMetadata | Record<string, string> | none | Your fields, added to every onUploadAsset call. |
inlineTemplateMedia | boolean | false | Saves pictures inside templates, even with onUploadAsset. |
See Saving and loading and Asset storage.
Opening with files uses the picture's own pixel size for its page. A supplied defaultTemplate keeps its page size. The mediaAddPolicy setting applies to later additions; stickers keep their existing placement.
Item locking
These options are part of item locking, which is new in
@layermetry/media-editor. Item locking needs version 1.0.0 or later; versions before 1.0.0 do not have these options.With the custom element, the attributes are editor-role, allow-unlock and default-locks. onUnlock is a function, so it can only be set in props. See Item locking in your framework guide.
| Name | Type | Default | Description |
|---|---|---|---|
role | 'creator' | 'adopter' | 'viewer' | 'adopter' | Who is editing. A creator ignores locks, an adopter obeys them, and a viewer changes nothing. |
allowUnlock | boolean | false | Lets an adopter ask to unlock items. A creator may always unlock. |
onUnlock | (event) => answer, or a Promise of an answer | none | Called before every unlock. Answer false, { allowed: false } or reject to refuse it. Answer { ref } to store your audit id in the unlock record. |
defaultLocks | object, for example { move: true } | the design's own | Replaces the design's own default locks for this session. A save never writes it. |
Print export
| Prop | Type | Default | Description |
|---|---|---|---|
printPlugin | ImagePrintPlugin | none | Enables commercial PDF settings when the host supplies the optional print implementation. Uses the existing editor license. See Print export. |
Events
| Name | Type | Default | Description |
|---|---|---|---|
onExport | (file: File, extras?: EditorExtras) => void | none | Receives the exported file after Save & Exit and Share. |
callback | (file: File, extras?: EditorExtras) => void | none | An older name for onExport. Use only one of them. |
onLicenseState | (report: LicenseStateReport) => void | none | Called each time the license state changes. |
See Events for the payloads, and the DOM events of the custom element.
License
| Name | Type | Default | Description |
|---|---|---|---|
apiUrl | string | https://api.layermetry.com/social | The address of the license server. Use HTTPS. |
statusUrl | string | none | The address of signed status files, read when the license server cannot be reached. Use HTTPS. |
renderLicenseBlocked | (state: BlockedState) => ReactNode | default screen | Your own screen in place of "License Validation Failed". |
See License validation.