Generation

Installation#

# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add generation

Usage#

import {
  Generation,
  GenerationHeader,
  GenerationIcon,
  GenerationLabel,
  GenerationStatus,
  GenerationActions,
  GenerationAction,
  GenerationPrompt,
  GenerationCanvas,
  GenerationImage,
  GenerationCaption,
  GenerationProgress,
  GenerationPercent,
  GenerationOverlay,
  GenerationGrid,
  GenerationFooter,
  GenerationMeta,
} from "@/components/ui/generation"

export function Example() {
  return (
    <Generation status="generating" progress={62} ratio="square">
      <GenerationHeader>
        <GenerationIcon><ImageSquare weight="bold" /></GenerationIcon>
        <GenerationLabel>Image</GenerationLabel>
      </GenerationHeader>

      <GenerationPrompt lines={2}>A valley at first light…</GenerationPrompt>

      <GenerationCanvas>
        <GenerationImage src={src} alt={alt} />
        <GenerationCaption />
        <GenerationProgress />
      </GenerationCanvas>

      <GenerationFooter>
        <GenerationMeta>Flux 1.1 · 1024×1024</GenerationMeta>
      </GenerationFooter>
    </Generation>
  )
}

Anatomy#

Four blocks, in reading order. An eyebrow says what kind of card this is (GenerationIcon + GenerationLabel, with a GenerationStatus chip or GenerationActions trailing). A GenerationPrompt quotes back what you asked for. The GenerationCanvas is the frame everything happens inside. A footer carries the meta and whatever you do next.

The frame never resizes. You know how big a picture will be long before you know what is in it, so the canvas takes its ratio up front: the card stands at its final height from the first frame, and nothing below it jumps when the bytes land. The picture is inset 8px from the card's edge with the radius that follows from it (24 − 8 = 16), the same geometry CardMedia uses, so the copy keeps its own, wider measure and the photograph reads as framed rather than as a header band.

PreviewCode

Image

A valley at first light, low cloud caught in the pines, long shadows, shot on medium format film

Flux 1.1 · 1536×1152 · 6.2sRegenerate

The reveal#

Mount the GenerationImage as soon as you have a URL, not when you are finished. Everything below it sits under a halftone screen whose holes open as progress climbs. At 62% you are looking at the picture through a plate that is 62% open — everywhere at once, the way a halftone resolves when you step back from it. The percentage stops being a number beside the picture and becomes the picture.

It glides rather than marches. The reveal is a registered custom property (--generation-reveal), which means a percentage that CSS can interpolate: a model reporting 40 → 62 → 100 reads as one continuous movement, and finishing just carries the number to 100, so the last stretch wipes in instead of cutting. Report no percentage at all and there is nothing to wipe to — the frame simply works at full size and a bar goes indeterminate, which is the honest reading.

The screen is the frame's own ground with two layers of one 12px dot grid drawn on it — small dots everywhere, large ones in the middle — breathing on a registered --generation-dot radius, so the plate swells and settles like something being worked on. The holes are punched half a cell off the dots, so they open between them and the dots are the last thing left standing. It is the part the frame keeps for itself: nothing to compose, nothing to remember to remove.

Nothing sweeps, nothing is tinted, and nothing travels in a direction. A shimmer passing over the frame, a blurred veil, a brand-coloured field, a lit hairline and a top-to-bottom wipe were each built and each thrown out: every one read as an effect laid over the work rather than as the work. A line crossing a picture reads as a scanner passing over it. The dots are plain ink at 30%, so they re-theme by themselves and leave the picture as the only coloured thing in the card.

Drag the percentage below to take the reveal at your own pace. Note the demo sets transition="none": a frame driven continuously — a slider under your finger, a stream reporting every frame — shouldn't ease, or it trails a third of a second behind you and reads as lag. It is the same axis, for the same reason, that Progress carries.

PreviewCode

Flux 1.1 · 38% painted

38%

States#

One status on the root moves the whole card: idle → generating → complete, or failed. Only the frame changes. While it works, the halftone screen sits over the picture and breathes; as the percentage climbs its holes open, and at 100% there is no plate left — the frame simply holds a photograph.

The state parts know when they aren't wanted. GenerationCaption and GenerationProgress render nothing once the picture is there; GenerationOverlay renders nothing until it is. Not hidden, not transparent — not in the DOM. So you leave all three in your markup unconditionally and never write a ternary around them.

PreviewCode

ImageReady

Nothing generated yet

Waiting on a prompt

ImageGenerating

Generating…

Flux 1.1 · 62%

ImageDone

Flux 1.1 · 6.2s

ImageFailed

That one didn't come out

Safety filter · no chargeTry again

Variations#

GenerationGrid lays a batch out as a contact sheet, two to four across. Each GenerationCanvas takes its own status, because a real batch comes back one tile at a time — so each frame keeps its own shimmer and settles when it is ready. Tiles land a beat apart rather than all at once, which is the difference between a sheet developing and four boxes appearing.

PreviewCode

4 variationsDone

A valley at first light, low cloud caught in the pines, long shadows, shot on medium format film

4 of 4 · Flux 1.1 · 1024×1024Run again

Ratios#

ratio on the root sizes the hero frame and every tile of a sheet at once: square, portrait (3:4), landscape (4:3), wide (16:9), tall (9:16), or auto when the height comes from the layout around it. A single GenerationCanvas can overrule it — a landscape hero over a square sheet is the common pair.

PreviewCode

square

portrait

wide

In a chat turn#

variant="plain" drops the ring, the shadow and the gutter so a generation sits inside a Chat turn or an AIPanel body as part of the answer rather than as a card inside a card. The picture then takes the full measure of the turn: there is nothing left for it to be inset from, so the inset lets go too.

PreviewCode

A valley at first light, low cloud caught in the pines, long shadows, shot on medium format film

Here's the valley at first light, with the cloud sitting low in the pines.

Flux 1.1 · 1536×1152 · 6.2s

API reference#

FAQ#