tinky-image

Terminal image rendering for Tinky.

Entry points

tinky-image exports the Node runtime by default:

import { Image } from "tinky-image";

<Image src="./logo.png" width={40} alt="logo" />;

Use the browser entry when your app is bundled with sharp-web:

import { Image } from "tinky-image/browser";

Demos

Run the CLI demo:

npm run demo:cli

For a non-interactive smoke check that renders once and exits:

npm run demo:cli -- --snapshot

Run the browser demo with tinky-web:

npm run demo:web

Build the browser demo bundle:

npm run demo:web:build

The browser demo renders the shared Tinky showcase app inside an Xterm.js surface provided by tinky-web, so the CLI and web examples stay aligned. Click the terminal and use the left/right arrow keys or 1-4 to switch renderers.

Source types

Node supports:

• File paths such as ./logo.png
• Absolute URLs such as https://example.com/logo.png
• Data URLs
• Uint8Array
• Blob

Browser supports:

• Relative URLs such as ./logo.png and /logo.png
• Absolute URLs such as https://example.com/logo.png
• blob: URLs
• Data URLs
• Uint8Array
• Blob

Sizing

width and height are measured in terminal cells. Each accepts a number of cells (width={40}) or a percentage of the terminal (width="50%"). The resizeMode prop controls how the image is fit into that box and defaults to "contain":

• "contain" (default) — scale to fit entirely inside the box, preserving aspect ratio. If only one of width/height is given, the other is derived from the source aspect ratio; if both are given, the image fits inside the box.
• "cover" — scale to fill the box, preserving aspect ratio. The image may overflow the box on one axis (the overflow is cropped by the terminal).
• "fill" — stretch to the exact width×height, ignoring aspect ratio.
• "none" — use the image's natural cell size, ignoring width/height.

<Image src="./logo.png" width={40} resizeMode="contain" />

Every mode except "none" clamps the rendered size to the current terminal bounds.

Backends

Backends are auto-detected in this order:

1. kitty
2. iterm
3. sixel
4. halfblock
5. braille
6. ascii

You can override detection with the renderer prop.

Backend overview

• kitty — terminal graphics protocol output for Kitty-compatible terminals
• iterm — inline image protocol output for iTerm2-compatible terminals
• sixel — bitmap graphics output for terminals that support Sixel
• halfblock — full-color text rendering using ANSI colors and the Unicode half-block character ▄
• braille — monochrome high-density rendering using Unicode Braille patterns
• ascii — plain character-art fallback for maximum compatibility