Image

Render binary image payloads (PNG or RGBA) with terminal image protocols.

Usage

ui.image({
  src: pngBytes,
  width: 20,
  height: 10,
  fit: "contain",
  protocol: "auto",
  alt: "Company logo",
})

Prop	Type	Default	Description
`src`	`Uint8Array`	required	PNG bytes or raw RGBA bytes
`sourceWidth`	`number`	-	Source pixel width (recommended for raw RGBA)
`sourceHeight`	`number`	-	Source pixel height (recommended for raw RGBA)
`width`	`number`	required	Width in terminal columns
`height`	`number`	required	Height in terminal rows
`fit`	`"fill" \| "contain" \| "cover"`	`"contain"`	Content fit mode
`protocol`	`"auto" \| "kitty" \| "sixel" \| "iterm2" \| "blitter"`	`"auto"`	Preferred transport protocol
`zLayer`	`-1 \| 0 \| 1`	`0`	Compositing layer
`imageId`	`number`	hash of `src`	Stable cache id for protocol backends
`alt`	`string`	-	Fallback text for unsupported/invalid images
`id`	`string`	-	Optional widget id
`key`	`string`	-	Reconciliation key

PNG is auto-detected by signature; non-PNG payloads are treated as RGBA bytes.
protocol: "auto" uses an internal fallback chain:
- RGBA: kitty -> iterm2 -> sixel -> canvas blitter -> alt placeholder
- PNG: iterm2 -> alt placeholder (kitty/sixel require RGBA)
Explicit protocol values still force that path (or render placeholder if incompatible).
For raw RGBA payloads, providing sourceWidth + sourceHeight avoids heuristic dimension inference.
Unsupported builders or invalid sources render a text placeholder (uses alt when present).
In Node/Bun, use loadImage(path) from @rezi-ui/node to read file paths into Uint8Array.