AI Image Editor UI & layout

The editor’s chrome is arranged from a few independent pieces. This page explains each and the properties that position them. Every option here is an attribute, so you can set it in HTML or as a property, and you can try them all live on the demo.

The pieces

• Canvas. The central stage where the image (or the idle dot grid) is shown.
• Composer. The bar holding the prompt input, the preset chips, and the aspect-ratio picker. It’s where the user types to generate or edit.
• History strip. The row of result thumbnails from the current session.
• Toolbar. The Cancel and Done actions.

Sizing

sizing decides who owns the editor’s height:

Fill (default)

Give the element a concrete box — the editor fills it, and the canvas letterboxes the image inside:

1
uc-ai-image-editor {
2
  max-width: 1200px;
3
  height: min(82vh, 820px);
4
}

An unsized host falls back to a 480px minimum height instead of collapsing; your own CSS on the element always wins over that fallback.

Content-driven height

With sizing="content" the editor grows and shrinks with the image: at the width you set, its height follows the aspect ratio currently on canvas — the picker selection while composing, the result’s own ratio once one exists — plus the composer/toolbar chrome. Constrain it with plain CSS on the host:

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
}

The canvas letterboxes whenever those limits clamp the derived height.

Composer position

composerPlacement picks which edge the composer sits on:

1
<uc-ai-image-editor composer-placement="top"></uc-ai-image-editor>

Canvas fit: docked vs. floating

canvasFit decides whether the composer sits outside the image or floats over it:

1
<uc-ai-image-editor canvas-fit="full"></uc-ai-image-editor>

History strip position

historyPlacement places the result-thumbnail strip either relative to the composer or pinned to a canvas edge:

Toolbar position

toolbarPlacement sets the edge for the Cancel / Done toolbar, either bottom (the default) or top. Setting it to none removes the toolbar entirely.

1
<uc-ai-image-editor toolbar-placement="top"></uc-ai-image-editor>

Bring your own toolbar

With toolbar-placement="none" the editor renders no Cancel or Done buttons. The stage reclaims their space, and your app provides the controls. Track the current result via the uc:change event, which fires whenever the result changes: a finished generation, a history-strip selection, or Start over, in which case detail.result is null. The payload has the same shape as uc:done (url, uuid, prompt, mode, aspectRatio, file). Every result is already an uploaded Uploadcare file, so result.file and result.url are usable immediately. Nothing about them waits for a “commit”.

1
<uc-ai-image-editor pubkey="YOUR_PUBLIC_KEY" toolbar-placement="none"></uc-ai-image-editor>
2
<button id="use" disabled>Use this image</button>

1
const editor = document.querySelector('uc-ai-image-editor');
2
const useBtn = document.querySelector('#use');
3
4
let current = null;
5
editor.addEventListener('uc:change', (e) => {
6
  current = e.detail.result; // DoneDetail | null
7
  useBtn.disabled = current === null;
8
});
9
useBtn.addEventListener('click', () => {
10
  save(current.url); // then close/remove the editor yourself
11
});

Closing is yours too. With no toolbar, uc:done and uc:cancel never fire, since their buttons are the only triggers. Use uc:change as the source of truth and remove or hide the editor whenever your UI decides the session is over.

In React the same pattern is the onChange prop; see the React guide.

Presets-only mode

presetsOnly hides the free-text prompt so only the preset chips remain, and picking a chip starts the generation immediately (there’s nothing to type, so no separate send step). Pair it with custom presets per mode.

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

Putting it together

These axes are orthogonal, so mix them freely. For example, a floating composer pinned to the top, with the history along the bottom of the canvas:

1
<uc-ai-image-editor
2
  composer-placement="top"
3
  canvas-fit="full"
4
  history-placement="canvas-bottom"
5
  toolbar-placement="top"
6
></uc-ai-image-editor>

See every option on the Options page.