Image

const Image: ForwardRefExoticComponent<ImageProps & RefAttributes<ImageHandle>>;

Inline image for terminal UIs.

Displays a placeholder until the user presses Space (or set autoLoad). Supports Kitty and iTerm2 graphics protocols for true inline rendering, with fallback to OS-level preview. Press Escape to unload.

Examples

<Image src="./logo.png" width={40} height={12} />

// Auto-load with auto-size
<Image
  src="https://example.com/photo.jpg"
  autoLoad
  autoSize
  maxWidth={60}
  maxHeight={20}
/>

---

Properties

Property	Type	Description
autoLoad?	boolean	Auto-load on mount (default: false - user presses space)
autoSize?	boolean	Auto-size the box to fit the image dimensions (default: false). When true, the box resizes to match the image’s aspect ratio. Use maxWidth/maxHeight to constrain the size.
disabled?	boolean	Whether the component is disabled (skipped in tab order, no key handling)
focusable?	boolean	Whether the component is focusable (default: true)
focusedStyle?	Style	Style when focused
height?	number	Fixed height in cells (optional, uses flexbox if not set)
inline?	boolean	Allow inline rendering in terminal (default: true)
maxHeight?	number	Maximum height in cells when autoSize is true
maxWidth?	number	Maximum width in cells when autoSize is true
onError?	(error) => void	Called on error
onStateChange?	(state) => void	Called when image state changes
placeholder?	string	Custom placeholder text (default: image name)
placeholderStyle?	Style	Style for the placeholder
src	string	Image source - local path or remote URL
style?	Style	Container style (flexbox)
unloadTrigger?	number	Force unload trigger - increment this value to force the image to unload. Useful when parent component handles Escape or other close actions. Example: <Image unloadTrigger={unloadCount} … />
width?	number	Fixed width in cells (optional, uses flexbox if not set)

---

ImageState

type ImageState = "placeholder" | "loading" | "loaded" | "error" | "preview";

Lifecycle state of the Image component.

• "placeholder" — waiting for user to press Space to load
• "loading" — image data is being fetched / decoded
• "loaded" — rendered inline via Kitty / iTerm2 protocol
• "error" — loading failed
• "preview" — opened via OS-level preview (Quick Look / xdg-open)

---

ImageHandle

Handle for Image

Extends

• FocusableHandle

Methods

blur()

blur(): void;

Programmatically blur (unfocus) this element

Returns

void

Inherited from

FocusableHandle.blur

---

focus()

focus(): void;

Programmatically focus this element

Returns

void

Inherited from

FocusableHandle.focus

---

scrollIntoView()

scrollIntoView(options?): void;

Scroll the nearest parent ScrollView to make this element visible. Behaves like the DOM Element.scrollIntoView() method. No-op if the element is not inside a ScrollView.

Parameters

Parameter	Type	Description
options?	ScrollIntoViewOptions	Alignment options (default: { block: "nearest" })

Returns

void

Example

const inputRef = useRef<InputHandle>(null);

// Minimal scroll — just enough to make it visible
inputRef.current?.scrollIntoView();

// Center the element in the viewport
inputRef.current?.scrollIntoView({ block: "center" });

Inherited from

FocusableHandle.scrollIntoView

Properties

Property	Modifier	Type	Description	Inherited from
isFocused	readonly	boolean	Whether this element is currently focused	FocusableHandle.isFocused