AI Image Editor options | Uploadcare docs

Every configuration option of the <uc-ai-image-editor> element. Options marked property only hold objects or functions, so they can’t be set as HTML attributes; assign them on the element from JavaScript. Everything else works both as an attribute and as a property. In React, each option maps to the prop of the same name; see the React guide.

Events and CSS custom properties are listed in the API reference.

Public key

Attribute: pubkey · Type: string · Default: ''

Uploadcare public key. Required to enable generate/edit. Grab one from the dashboard (see API keys).

1 <uc-ai-image-editor pubkey="YOUR_PUBLIC_KEY"></uc-ai-image-editor>

Source UUID

Attribute: source-uuid · Type: string | null · Default: null

UUID of an image to edit. When set (or sourceFileInfo is), the editor opens straight in edit mode; when absent, it starts in generate mode. Use either sourceUuid or sourceFileInfo, not both. They’re two ways to point at the same source: a UUID the editor looks up, or the already-resolved file.

1 editor.sourceUuid = 'c2499162-eb07-4b93-b31e-94a89a47e858';

Source file info

Property only · Type: UploadcareFile | undefined

The source image as an UploadcareFile, e.g. the object returned by @uploadcare/upload-client, or the fileInfo of a File Uploader output entry (OutputFileEntry.fileInfo). Hands the editor the file directly instead of having it look it up from a UUID. Use either sourceFileInfo or sourceUuid, not both.

Output filename

Property only · Type: string | OutputFilenameResolver | undefined

Names the generated/edited result. A string is used verbatim; a function receives (originalFilename, counter) and returns the name (see OutputFilenameResolver). When unset, the result keeps the source’s original filename (and falls back to the provider’s default when generating from scratch).

1 editor.outputFilename = (original, counter) => `ai-${counter}-${original}`;

Metadata

Property only · Type: Metadata | MetadataCallback | null | undefined

Metadata attached to the resulting Uploadcare file, for both generate and edit. Mirrors the File Uploader’s metadata config: either a static bag (Record<string, string>) or a MetadataCallback resolved at generation time against the source file.

1 editor.metadata = { source: 'ai-image-editor' };

Base URL

Attribute: base-url · Type: string | undefined

Upload API base URL. Defaults to the provider’s default.

CDN cname

Attribute: cdn-cname · Type: string | undefined

Custom CDN CNAME for resolving results.

CDN cname prefixed

Attribute: cdn-cname-prefixed · Type: string | undefined

Base domain for public-key-prefixed CDN URLs.

Secure delivery proxy URL resolver

Property only · Type: SecureDeliveryProxyUrlResolver | undefined

Secure-delivery resolver: signs/proxies the CDN URLs the editor renders. See signed URLs and the SecureDeliveryProxyUrlResolver type.

Aspect ratios

Attribute: aspect-ratios · Type: AspectRatio[] | null · Default: null

Available aspect ratios for the generate flow. When set as an attribute, the string is parsed; falsy/empty input falls back to the popular set.

1 <uc-ai-image-editor aspect-ratios="16:9 5:4 1:1"></uc-ai-image-editor>

1 editor.aspectRatios = [[16, 9], [5, 4], [1, 1]];

Locale name

Attribute: locale-name · Type: string · Default: 'en'

Active locale. The editor lazy-loads its built-in strings for this locale (falling back to English) and layers localeDefinitionOverride on top. See Localization.

Locale definition override

Property only · Type: Record<string, Partial<AiImageEditorLocale>> · Default: {}

Locale string overrides, keyed by locale name, in the same shape as the File Uploader’s localeDefinitionOverride. The section matching localeName is layered on top of that locale’s built-in strings.

1 editor.localeDefinitionOverride = {
2   en: { 'ai-image-editor-generate-btn': 'Make it!' },
3 };

Presets

Property only · Type: AiPresets · Default: {}

Quick-prompt presets (the chips above the prompt), keyed by mode. Each preset is { label, prompt }: clicking a chip fills the prompt with prompt. Modes left out use their built-in set; an empty array hides that mode’s chips.

1 editor.presets = {
2   generate: [{ label: 'Logo', prompt: 'A logo of ' }],
3   edit: [],
4 };

Keyed by AiEditorMode (and partial), so new modes (e.g. outpaint) extend this additively, without breaking existing configs.

Presets only

Attribute: presets-only · Type: boolean · Default: false

Presets-only mode: hides the free-text prompt so only the preset chips remain, and selecting a preset starts the generation immediately (there’s nothing to type, so no separate send step).

1 <uc-ai-image-editor presets-only></uc-ai-image-editor>

Composer placement

Attribute: composer-placement · Type: 'bottom' | 'top' · Default: 'bottom'

Which edge the composer (prompt input, presets, aspect-ratio picker) sits on. See UI & layout.

Canvas fit

Attribute: canvas-fit · Type: 'available' | 'full' · Default: 'available'

How the canvas sizes relative to the composer. available (default) shrinks the canvas to the space left by the composer, which is docked outside the image. full lets the canvas fill the whole area with the composer floating over it.

Sizing

Attribute: sizing · Type: 'fill' | 'content' · Default: 'fill'

Who owns the editor’s height. fill (default) makes the editor fill the box you give it — size the host element explicitly with CSS. content fixes the width instead and lets the editor derive its own height from the aspect ratio currently on canvas, within any min-height / max-height you set.

1 <uc-ai-image-editor sizing="content"></uc-ai-image-editor>

1 uc-ai-image-editor {
2   width: 720px;
3   min-height: 360px;
4   max-height: 85vh;
5 }

An unsized host in fill mode falls back to a 480px minimum height rather than collapsing; your own CSS on the element always wins over that fallback. The mode is CSS-driven off the reflected attribute, so an unknown value behaves as fill. See UI & layout.

History placement

Attribute: history-placement · Type: 'composer-above' | 'composer-below' | 'canvas-top' | 'canvas-bottom' · Default: 'composer-above'

Where the history strip sits. composer-above / composer-below are relative to the composer; canvas-top / canvas-bottom pin it to the canvas edge.

Attribute: toolbar-placement · Type: 'bottom' | 'top' | 'none' · Default: 'bottom'

Where the toolbar (Cancel / Done) sits, either bottom (the default) or top. Setting it to none removes the toolbar entirely, in which case your app provides the controls; see Bring your own toolbar.