AI Image Editor

Appearance

Class: UcAiImageEditor ​

Defined in: packages/ai-image-editor/src/widgets/ai-editor/ui/UcAiImageEditor.ts:181

<uc-ai-image-editor> — the standalone AI image generate/edit editor.

Generates images from a text prompt and edits an existing image (set sourceUuid or sourceFileInfo), backed by Uploadcare's derivative API (configured via pubkey).

Fires ​

EventDescription
uc:doneA CustomEvent<DoneDetail> fired when the user commits a result (the Done button). detail carries the result url, uuid, prompt, mode, optional aspectRatio, and the file object.
uc:cancelFired when the user cancels (the Cancel button). No detail.
uc:changeA CustomEvent<ChangeDetail> fired whenever the current generation result changes (finished generation, history selection, or reset — then detail.result is null). Lets a host drive its own chrome when the toolbar is hidden (toolbar-placement="none").
uc:errorA CustomEvent<ErrorDetail> fired when a generation throws. detail.error is always an AiImageEditorError — its code maps to a localized message and the original thrown value is on .cause.

CSS Custom Properties ​

PropertyDescription
--uc-ai-backgroundEditor surface background.
--uc-ai-foregroundPrimary text/icon colour.
--uc-ai-muted-foregroundSecondary/muted text colour.
--uc-ai-accentAccent colour for primary actions.
--uc-ai-radius-buttonCorner radius for buttons.
--uc-ai-transitionBase transition timing.
--uc-ai-dot-grid-colorColour of the shimmer dot grid.

See ​

The theming guide for the full token list.

Properties ​

aspectRatios ​

ts
aspectRatios: AspectRatio[] | null = null;

Defined in: packages/ai-image-editor/src/widgets/ai-editor/ui/UcAiImageEditor.ts:291

Available aspect ratios for the generate flow. When set as an attribute (aspect-ratios="16:9 5:4 1:1"), the string is parsed. Falsy / empty input falls back to the popular set.

authToken? ​

ts
optional authToken?: AuthToken;

Defined in: packages/ai-image-editor/src/widgets/ai-editor/ui/UcAiImageEditor.ts:246

JWT for the Upload API Authorization: Bearer scheme. Either a plain token — which is what a server-rendered page passes in — or a function returning one.

The editor caches what the function returns and refreshes it shortly before it expires, so the function can fetch from your backend without being called once per request. A plain token is used as given and never refreshed.

The auth-token attribute carries the plain-token form only; a function has to be set as a DOM property.

baseUrl? ​

ts
optional baseUrl?: string;

Defined in: packages/ai-image-editor/src/widgets/ai-editor/ui/UcAiImageEditor.ts:271

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

cacheAuthToken ​

ts
cacheAuthToken: boolean = true;

Defined in: packages/ai-image-editor/src/widgets/ai-editor/ui/UcAiImageEditor.ts:257

Whether to cache what an authToken function returns. Defaults to true.

Set it to false when something upstream already caches — the file uploader hands its plugin an authToken that its own cache backs, and wrapping that again would just add a second layer with its own idea of when the token went stale. Property only.

canvasFit ​

ts
canvasFit: CanvasFit = 'available';

Defined in: packages/ai-image-editor/src/widgets/ai-editor/ui/UcAiImageEditor.ts:338

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 (history chips still overlay the canvas). full lets the canvas fill the whole area with the composer floating over it.

cdnCname? ​

ts
optional cdnCname?: string;

Defined in: packages/ai-image-editor/src/widgets/ai-editor/ui/UcAiImageEditor.ts:275

CDN cname for resolving results (maps to the provider's cdnBaseUrl).

cdnCnamePrefixed? ​

ts
optional cdnCnamePrefixed?: string;

Defined in: packages/ai-image-editor/src/widgets/ai-editor/ui/UcAiImageEditor.ts:279

Base domain for public-key-prefixed CDN URLs.

composerPlacement ​

ts
composerPlacement: ComposerPlacement = 'bottom';

Defined in: packages/ai-image-editor/src/widgets/ai-editor/ui/UcAiImageEditor.ts:329

Which edge the composer sits on: bottom (default) or top.

historyPlacement ​

ts
historyPlacement: HistoryPlacement = 'composer-above';

Defined in: packages/ai-image-editor/src/widgets/ai-editor/ui/UcAiImageEditor.ts:359

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

localeDefinitionOverride ​

ts
localeDefinitionOverride: Record<string, Partial<AiImageEditorLocale>> = {};

Defined in: packages/ai-image-editor/src/widgets/ai-editor/ui/UcAiImageEditor.ts:305

Locale string overrides, keyed by locale name — the same shape as the file uploader's localeDefinitionOverride. The section matching localeName is layered on top of that locale's built-in strings, e.g. { en: { 'ai-image-editor-generate-btn': 'Make it!' } }.

localeName ​

ts
localeName: string = 'en';

Defined in: packages/ai-image-editor/src/widgets/ai-editor/ui/UcAiImageEditor.ts:296

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

metadata? ​

ts
optional metadata?: 
  | Metadata
  | MetadataCallback
  | null;

Defined in: packages/ai-image-editor/src/widgets/ai-editor/ui/UcAiImageEditor.ts:226

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>, e.g. { source: 'ai-image-editor' }) or a MetadataCallback resolved at generation time against the source file. Property only.

outputFilename? ​

ts
optional outputFilename?: 
  | string
  | OutputFilenameResolver;

Defined in: packages/ai-image-editor/src/widgets/ai-editor/ui/UcAiImageEditor.ts:216

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). Property only (the function form can't be an attribute).

presets ​

ts
presets: AiPresets = {};

Defined in: packages/ai-image-editor/src/widgets/ai-editor/ui/UcAiImageEditor.ts:325

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, e.g. { generate: [{ label: 'Logo', prompt: 'A logo of ' }], edit: [] }.

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

presetsOnly ​

ts
presetsOnly: boolean = false;

Defined in: packages/ai-image-editor/src/widgets/ai-editor/ui/UcAiImageEditor.ts:313

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). Off by default.

pubkey ​

ts
pubkey: string = '';

Defined in: packages/ai-image-editor/src/widgets/ai-editor/ui/UcAiImageEditor.ts:230

Uploadcare public key. Required to enable generate/edit.

secureDeliveryProxyUrlResolver? ​

ts
optional secureDeliveryProxyUrlResolver?: SecureDeliveryProxyUrlResolver;

Defined in: packages/ai-image-editor/src/widgets/ai-editor/ui/UcAiImageEditor.ts:283

Secure-delivery resolver: signs/proxies the CDN urls the editor renders.

sizing ​

ts
sizing: Sizing = 'fill';

Defined in: packages/ai-image-editor/src/widgets/ai-editor/ui/UcAiImageEditor.ts:351

How the editor's own box is sized. fill (default) keeps the host at width/height: 100% — size it explicitly via its container or own CSS. content derives the editor's height from the canvas's aspect ratio at the width you set: give the host a width and optional min-height / max-height in plain CSS, and the editor grows and shrinks with the active ratio within those limits (the canvas letterboxes when clamped). The mode is CSS-driven off the reflected attribute, so an unknown value behaves as fill.

sourceFileInfo? ​

ts
optional sourceFileInfo?: UploadcareFile;

Defined in: packages/ai-image-editor/src/widgets/ai-editor/ui/UcAiImageEditor.ts:206

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. Property only.

sourceUuid ​

ts
sourceUuid: string | null = null;

Defined in: packages/ai-image-editor/src/widgets/ai-editor/ui/UcAiImageEditor.ts:194

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, vs. the already-resolved file). The mode is otherwise derived (see _mode).

toolbarPlacement ​

ts
toolbarPlacement: ToolbarPlacement = 'bottom';

Defined in: packages/ai-image-editor/src/widgets/ai-editor/ui/UcAiImageEditor.ts:378

Where the toolbar (Cancel / Done) sits: bottom (default) or top. none hides the toolbar entirely — the host provides its own chrome, tracking the current result via the uc:change event.

Methods ​

invalidateAuthToken() ​

ts
invalidateAuthToken(): void;

Defined in: packages/ai-image-editor/src/widgets/ai-editor/ui/UcAiImageEditor.ts:536

Drop the cached auth token, so the next request calls authToken for a new one.

Assigning a different function to authToken does not do this on its own: a new function identity is taken to be the same function, which is what lets a parent component pass an inline one without refetching on every render. Call this when the change is real, such as when the signed-in user changes. It does nothing when authToken is a plain token, since there is no cache to drop.

Returns ​

void