Class: UcAiEnhancer
Defined in: packages/ai-enhancer/src/widgets/ai-editor/ui/UcAiEnhancer.ts:159
<uc-ai-enhancer> — 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
| Event | Description |
|---|---|
uc:done | A 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:cancel | Fired when the user cancels (the Cancel button). No detail. |
uc:change | A 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:error | A CustomEvent<ErrorDetail> fired when a generation throws. detail.error is always an AiEnhancerError — its code maps to a localized message and the original thrown value is on .cause. |
CSS Custom Properties
| Property | Description |
|---|---|
--uc-ai-background | Editor surface background. |
--uc-ai-foreground | Primary text/icon colour. |
--uc-ai-muted-foreground | Secondary/muted text colour. |
--uc-ai-accent | Accent colour for primary actions. |
--uc-ai-radius-button | Corner radius for buttons. |
--uc-ai-transition | Base transition timing. |
--uc-ai-dot-grid-color | Colour of the shimmer dot grid. |
See
The theming guide for the full token list.
Properties
aspectRatios
aspectRatios: AspectRatio[] | null = null;Defined in: packages/ai-enhancer/src/widgets/ai-editor/ui/UcAiEnhancer.ts:242
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.
baseUrl?
optional baseUrl?: string;Defined in: packages/ai-enhancer/src/widgets/ai-editor/ui/UcAiEnhancer.ts:222
Upload API base URL. Defaults to the provider's default.
canvasFit
canvasFit: CanvasFit = 'available';Defined in: packages/ai-enhancer/src/widgets/ai-editor/ui/UcAiEnhancer.ts:289
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?
optional cdnCname?: string;Defined in: packages/ai-enhancer/src/widgets/ai-editor/ui/UcAiEnhancer.ts:226
CDN cname for resolving results (maps to the provider's cdnBaseUrl).
cdnCnamePrefixed?
optional cdnCnamePrefixed?: string;Defined in: packages/ai-enhancer/src/widgets/ai-editor/ui/UcAiEnhancer.ts:230
Base domain for public-key-prefixed CDN URLs.
composerPlacement
composerPlacement: ComposerPlacement = 'bottom';Defined in: packages/ai-enhancer/src/widgets/ai-editor/ui/UcAiEnhancer.ts:280
Which edge the composer sits on: bottom (default) or top.
historyPlacement
historyPlacement: HistoryPlacement = 'composer-above';Defined in: packages/ai-enhancer/src/widgets/ai-editor/ui/UcAiEnhancer.ts:297
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
localeDefinitionOverride: Record<string, Partial<AiEnhancerLocale>> = {};Defined in: packages/ai-enhancer/src/widgets/ai-editor/ui/UcAiEnhancer.ts:256
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-enhancer-generate-btn': 'Make it!' } }.
localeName
localeName: string = 'en';Defined in: packages/ai-enhancer/src/widgets/ai-editor/ui/UcAiEnhancer.ts:247
Active locale. The editor lazy-loads its built-in strings for this locale (falling back to English) and layers localeDefinitionOverride on top.
metadata?
optional metadata?:
| Metadata
| MetadataCallback
| null;Defined in: packages/ai-enhancer/src/widgets/ai-editor/ui/UcAiEnhancer.ts:204
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-enhancer' }) or a MetadataCallback resolved at generation time against the source file. Property only.
outputFilename?
optional outputFilename?:
| string
| OutputFilenameResolver;Defined in: packages/ai-enhancer/src/widgets/ai-editor/ui/UcAiEnhancer.ts:194
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
presets: AiPresets = {};Defined in: packages/ai-enhancer/src/widgets/ai-editor/ui/UcAiEnhancer.ts:276
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
presetsOnly: boolean = false;Defined in: packages/ai-enhancer/src/widgets/ai-editor/ui/UcAiEnhancer.ts:264
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
pubkey: string = '';Defined in: packages/ai-enhancer/src/widgets/ai-editor/ui/UcAiEnhancer.ts:208
Uploadcare public key. Required to enable generate/edit.
secureDeliveryProxyUrlResolver?
optional secureDeliveryProxyUrlResolver?: SecureDeliveryProxyUrlResolver;Defined in: packages/ai-enhancer/src/widgets/ai-editor/ui/UcAiEnhancer.ts:234
Secure-delivery resolver: signs/proxies the CDN urls the editor renders.
sourceFileInfo?
optional sourceFileInfo?: UploadcareFile;Defined in: packages/ai-enhancer/src/widgets/ai-editor/ui/UcAiEnhancer.ts:184
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
sourceUuid: string | null = null;Defined in: packages/ai-enhancer/src/widgets/ai-editor/ui/UcAiEnhancer.ts:172
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
toolbarPlacement: ToolbarPlacement = 'bottom';Defined in: packages/ai-enhancer/src/widgets/ai-editor/ui/UcAiEnhancer.ts:316
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.