> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://uploadcare.com/docs/llms.txt. # AI Image Editor options > List of all available configuration options for the AI Image Editor web component. Every configuration option of the `` 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](/docs/ai-image-editor/react/). Events and CSS custom properties are listed in the [API reference](https://uploadcare.github.io/ai-image-editor/api/components?utm_source=uploadcare-docs\&utm_medium=docs\&utm_campaign=ai-image-editor). ## Public key \[#pubkey] Attribute: `pubkey` · Type: `string` · Default: `''` Uploadcare public key. Required to enable generate/edit. Grab one from the [dashboard](https://app.uploadcare.com/) (see [API keys](/docs/start/settings/#keys)). ```html ``` ## Source UUID \[#source-uuid] Attribute: `source-uuid` · Type: `string | null` · Default: `null` UUID of an image to edit. When set (or [`sourceFileInfo`](#source-file-info) 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. ```js editor.sourceUuid = 'c2499162-eb07-4b93-b31e-94a89a47e858'; ``` ## Source file info \[#source-file-info] Property only · Type: `UploadcareFile | undefined` The source image as an `UploadcareFile`, e.g. the object returned by [`@uploadcare/upload-client`](/docs/uploading-files/), 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`](#source-uuid), not both. ## Output filename \[#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`](https://uploadcare.github.io/ai-image-editor/api/typescript/type-aliases/OutputFilenameResolver?utm_source=uploadcare-docs\&utm_medium=docs\&utm_campaign=ai-image-editor)). When unset, the result keeps the source's original filename (and falls back to the provider's default when generating from scratch). ```js editor.outputFilename = (original, counter) => `ai-${counter}-${original}`; ``` ## Metadata \[#metadata] Property only · Type: `Metadata | MetadataCallback | null | undefined` [Metadata](/docs/file-metadata/) attached to the resulting Uploadcare file, for both generate and edit. Mirrors the File Uploader's `metadata` config: either a static bag (`Record`) or a `MetadataCallback` resolved at generation time against the source file. ```js editor.metadata = { source: 'ai-image-editor' }; ``` ## Base URL \[#base-url] Attribute: `base-url` · Type: `string | undefined` Upload API base URL. Defaults to the provider's default. ## CDN cname \[#cdn-cname] Attribute: `cdn-cname` · Type: `string | undefined` [Custom CDN CNAME](/docs/delivery/cdn/#settings) for resolving results. ## CDN cname prefixed \[#cdn-cname-prefixed] Attribute: `cdn-cname-prefixed` · Type: `string | undefined` Base domain for public-key-prefixed CDN URLs. ## Secure delivery proxy URL resolver \[#secure-delivery-proxy-url-resolver] Property only · Type: `SecureDeliveryProxyUrlResolver | undefined` Secure-delivery resolver: signs/proxies the CDN URLs the editor renders. See [signed URLs](/docs/security/secure-delivery/) and the [`SecureDeliveryProxyUrlResolver`](https://uploadcare.github.io/ai-image-editor/api/typescript/type-aliases/SecureDeliveryProxyUrlResolver?utm_source=uploadcare-docs\&utm_medium=docs\&utm_campaign=ai-image-editor) type. ## Aspect ratios \[#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. ```html ``` ```js editor.aspectRatios = [[16, 9], [5, 4], [1, 1]]; ``` ## Locale name \[#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`](#locale-definition-override) on top. See [Localization](/docs/ai-image-editor/localization/). ## Locale definition override \[#locale-definition-override] Property only · Type: `Record>` · Default: `{}` Locale string overrides, keyed by locale name, in the same shape as the File Uploader's `localeDefinitionOverride`. The section matching [`localeName`](#locale-name) is layered on top of that locale's built-in strings. ```js editor.localeDefinitionOverride = { en: { 'ai-image-editor-generate-btn': 'Make it!' }, }; ``` ## Presets \[#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. ```js editor.presets = { generate: [{ label: 'Logo', prompt: 'A logo of ' }], edit: [], }; ``` Keyed by `AiEditorMode` (and partial), so new modes (e.g. `outpaint`) extend this additively, without breaking existing configs. ## Presets only \[#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). ```html ``` ## Composer placement \[#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](/docs/ai-image-editor/layout/). ## Canvas fit \[#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 \[#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. ```html ``` ```css uc-ai-image-editor { width: 720px; min-height: 360px; max-height: 85vh; } ``` 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](/docs/ai-image-editor/layout/#sizing). ## History placement \[#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. ## Toolbar placement \[#toolbar-placement] 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](/docs/ai-image-editor/layout/#bring-your-own-toolbar).