Components
The web-component API for <uc-ai-enhancer> — attributes, properties, events, slots, and CSS custom properties.
<uc-ai-enhancer>
Properties & attributes
| Property | Attribute | Type | Default | Description |
|---|---|---|---|---|
sourceUuid | source-uuid | string | null | 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, vs. the already-resolved file). The mode is otherwise derived (see _mode). |
sourceFileInfo | — | 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. Property only. | |
outputFilename | — | 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). Property only (the function form can't be an attribute). | |
metadata | — | 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>, e.g. { source: 'ai-enhancer' }) or a MetadataCallback resolved at generation time against the source file. Property only. | |
pubkey | pubkey | string | '' | Uploadcare public key. Required to enable generate/edit. |
baseUrl | base-url | string | undefined | Upload API base URL. Defaults to the provider's default. | |
cdnCname | cdn-cname | string | undefined | CDN cname for resolving results (maps to the provider's cdnBaseUrl). | |
cdnCnamePrefixed | cdn-cname-prefixed | string | undefined | Base domain for public-key-prefixed CDN URLs. | |
secureDeliveryProxyUrlResolver | — | SecureDeliveryProxyUrlResolver | undefined | Secure-delivery resolver: signs/proxies the CDN urls the editor renders. | |
aspectRatios | aspect-ratios | AspectRatio[] | null | null | 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. |
localeName | locale-name | string | 'en' | Active locale. The editor lazy-loads its built-in strings for this locale (falling back to English) and layers localeDefinitionOverride on top. |
localeDefinitionOverride | — | Record<string, Partial<AiEnhancerLocale>> | {} | 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!' } }. |
presetsOnly | presets-only | boolean | 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). Off by default. |
presets | — | AiPresets | {} | 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. |
composerPlacement | composer-placement | ComposerPlacement | 'bottom' | Which edge the composer sits on: bottom (default) or top. |
canvasFit | canvas-fit | CanvasFit | '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 (history chips still overlay the canvas). full lets the canvas fill the whole area with the composer floating over it. |
historyPlacement | history-placement | HistoryPlacement | 'composer-above' | 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. |
toolbarPlacement | toolbar-placement | ToolbarPlacement | 'bottom' | 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. |
Events
| Event | Type | Description |
|---|---|---|
uc:error | CustomEvent | 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. |
uc:done | CustomEvent | 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 | CustomEvent | Fired when the user cancels (the Cancel button). No detail. |
uc:change | CustomEvent | 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"). |
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. |