ImageControl

Displays an image in the terminal — full-resolution via the Kitty graphics protocol, with a half-block fallback everywhere else.

The full reference for this control lives in Image Rendering. This page is a short orientation and a set of links into it.

Overview

ImageControl renders a PixelBuffer into a window. On terminals that support the Kitty graphics protocol (Kitty, WezTerm, Ghostty) it draws the image at full pixel resolution; elsewhere it falls back to half-block cells, which gives two vertical pixels per character row. Detection is automatic — you do not choose the path.

Supported formats are PNG, JPEG, BMP, GIF, WebP and TIFF, loaded from a path, a stream, or an ImageSharp image.

Quick Start

var pixels = PixelBuffer.FromFile("photo.png");

window.AddControl(Controls.Image(pixels));

With the builder, when you need layout or identity options:

var image = Controls.Image()
    .WithSource(pixels)
    .WithScaleMode(ImageScaleMode.Fill)
    .WithAlignment(HorizontalAlignment.Center)
    .WithName("preview")
    .Build();

Where to read more

Topic	Section
Properties (Source, ScaleMode, MinimumWidth, MinimumHeight)	ImageControl → Properties
All builder methods	ImageControl → Builder API
Creating and filling pixel data	PixelBuffer
Loading from files, streams, ImageSharp, or a file picker	Loading Images from Files
Fit / Fill / Stretch / None and how they behave	Scale Modes
How alignment interacts with scale mode	Alignment and Scale Mode Interaction
Terminal support and how detection works	Kitty Graphics Protocol
The fallback renderer	Half-Block Rendering

See Also

• Image Rendering — the complete guide
• VideoControl — moving images, same rendering backends
• CanvasControl — draw your own graphics cell by cell
• Controls Reference — all controls

---

Back to Controls | Back to Main Documentation