Xzero UI
Pro library
Special componentsImage generation

Image generationPro

An image generation card where four images resolve as a pixel mosaic, from coarse colour blocks to full detail under a soft shimmer, each with its own progress ring. Pick one to upscale with a sweeping pixel band, vary or download it, with real provider marks and a built-in simulation.

$ pnpm dlx shadcn@4.23.0 add @xzero-ui-pro/image-generation
Live · keyboard ready

When to use

When not to use

Installation

Register both Xzero UI namespaces in your project's components.json:

{
  "registries": {
    "@xzero-ui": "https://mcp.xzero.co.uk/r/{name}.json",
    "@xzero-ui-pro": "https://mcp.xzero.co.uk/r/pro/{name}.json"
  }
}

npx shadcn@4.23.0 add @xzero-ui-pro/image-generation

Install xzero-foundation once, and import @/components/xzero/foundation.css in your app root. No Xzero token is used by this snapshot. For sample portraits, photos, fonts, or logos, download https://mcp.xzero.co.uk/install-assets.mjs and run node xzero-install-assets.mjs <receiving-project>.

Usage

import { ImageGeneration } from "@/components/xzero/image-generation/image-generation";

export function Studio() {
  return <ImageGeneration
    onGenerate={async (request, { signal, onProgress }) => {
      const job = await fetch("/api/images", {
        method: "POST",
        signal,
        body: JSON.stringify({ prompt: request.prompt, model: request.model.id, size: `${request.aspect.width}x${request.aspect.height}`, seedFrom: request.variationOf?.id }),
      }).then(response => response.json());
      onProgress(1);
      return { id: job.id, src: job.url, alt: request.prompt, width: request.aspect.width, height: request.aspect.height };
    }}
    onDownload={image => window.open(image.src)}
  />;
}

API reference

ImageGeneration

An image generation card: prompt, model and aspect chips, and a 2×2 grid where each image resolves as a pixel mosaic, from coarse colour blocks to full detail, under its own progress ring. Pick one to upscale (it expands to fill the grid), vary or download. With no props it runs a local simulation on sample photos.

PropTypeDefaultDescription
promptstring–Controlled prompt. Pair with onPromptChange.
defaultPromptstringsample golden hour landscape promptStarting prompt when uncontrolled.
onPromptChange(prompt: string) => void–Fires as the person types or picks a suggestion.
modelsImageGenerationModel[]imageGenerationModelsModels offered as chips: { id, name, mark? }. The chosen chip shows its name, the others collapse to their 16px mark with a tooltip.
modelstring–Controlled model id. Pair with onModelChange.
defaultModelstringfirst modelStarting model id when uncontrolled.
onModelChange(id: string) => void–Fires when a model chip is chosen.
aspectRatiosImageGenerationAspect[]1:1, 4:5, 16:9Output shapes: { id, label, width, height }. Width and height are the pixels a generation returns and drive the grid's shape.
aspectRatiostring–Controlled aspect id. Pair with onAspectRatioChange.
defaultAspectRatiostringfirst ratioStarting aspect id when uncontrolled.
onAspectRatioChange(id: string) => void–Fires when an aspect chip is chosen. The new shape applies to the next generation; the current grid keeps its own.
onGenerate(request: ImageGenerationRequest, context: { signal: AbortSignal; onProgress(progress: number, preview?: string): void }) => Promise<ImageGenerationImage>simulateImageGenerationProduces one image. Called once per tile, in parallel, for Generate, Vary (request.variationOf is set) and Retry. Report progress from 0 to 1, optionally with a preview URL that the pixel mosaic resolves from (without one, a quiet placeholder grid shimmers until the image arrives and fades in); without reports the ring estimates. Reject to mark that tile failed; the signal aborts on Stop.
onUpscale(image: ImageGenerationImage, context: ImageGenerationContext) => Promise<ImageGenerationImage>simulateImageUpscaleUpscales the chosen image while it is expanded. Return the new image with its width and height.
onDownload(image: ImageGenerationImage) => void–Replaces the built in download, which saves image.src with a file name built from the prompt, index and size.
onSelect(image: ImageGenerationImage | null) => void–Fires when the person picks or clears an image, and with the upscaled image once an upscale finishes.
suggestionsstring[]three sample promptsPrompts offered in the empty grid before the first generation.
autoGeneratebooleantrue with the simulation, false with onGenerateGenerates once when the card first scrolls into view, then picks image 1 if nobody has touched the card.
placeholderstring"Describe the image you want"Prompt placeholder.
classNamestring–Class on the card.

simulateImageGeneration

The built in generator, exported so you can wrap it in tests or demos. Picks sample photos that match the prompt and reports frame by frame progress over about two to three seconds. Nothing is sent anywhere.

No props.

Keyboard interactions

KeysAction
Cmd/Ctrl + EnterGenerate from the prompt field.
Arrow keysMove between model chips or aspect chips (radio groups), and between images in the grid.
Enter / SpacePick or clear the focused image.
EscapeClose the expanded image and return to the grid.
TabPrompt, model, aspect, Generate, the selected image, then Upscale, Vary and Download.

Accessibility

Motion

Responsive behavior

Performance

Notes for AI

Also in ai

Guidance for AI tools

Image generation: An image generation card where four images resolve as a pixel mosaic, from coarse colour blocks to full detail under a soft shimmer, each with its own progress ring. Pick one to upscale with a sweeping pixel band, vary or download it, with real provider marks and a built-in simulation. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://ui.xzero.co.uk/llms.txt

Browse all components