terminal-image

The library automatically detects and uses the best available protocol for image rendering:

1. Kitty Graphics Protocol: Full resolution support in Kitty, Konsole, and WezTerm (when configured).
2. iTerm2 Inline Images Protocol: Full resolution support in iTerm2 and compatible terminals.
3. ANSI Block Characters: Universal fallback using Unicode half-blocks with 24-bit color (works in any terminal that supports colors).

Install the terminal-image package via npm to display images in the terminal.

npm install terminal-image

You can scale images using the width and height options. These can be specified as a percentage of the terminal window (e.g., '50%') or as a specific number of columns/rows (e.g., 50).

By default, the aspect ratio is maintained. To ignore the aspect ratio, set preserveAspectRatio: false.

import terminalImage from 'terminal-image';

// Scale by percentage
console.log(await terminalImage.file('unicorn.jpg', {width: '50%', height: '50%'}));

// Scale by columns
console.log(await terminalImage.file('unicorn.jpg', {width: 50}));

// Disable aspect ratio preservation
console.log(await terminalImage.file('unicorn.jpg', {width: 70, height: 50, preserveAspectRatio: false}));

Use terminalImage.file(filePath, options?) to display an image from a file path. It returns a Promise<string> containing the ANSI escape codes required to render the image in the terminal.

import terminalImage from 'terminal-image';

console.log(await terminalImage.file('unicorn.jpg'));

Use terminalImage.buffer(imageBuffer, options?) to display an image from a Buffer. It returns a Promise<string> containing the ANSI escape codes required to render the image in the terminal.

import terminalImage from 'terminal-image';
import got from 'got';

const body = await got('https://sindresorhus.com/unicorn').buffer();
console.log(await terminalImage.buffer(body));

Options available exclusively when using terminalImage.gifBuffer or terminalImage.gifFile.

##### maximumFrameRate
**Only works for `terminalImage.gifBuffer` or `terminalImage.gifFile`**
Type: `number`\nDefault: `30`\nMaximum framerate to render the GIF. This option is ignored when using iTerm.

##### renderFrame
**Only works for `terminalImage.gifBuffer` or `terminalImage.gifFile`**
Type: `(text: string) => void`\nDefault: [log-update](https://github.com/sindresorhus/log-update)\nCustom handler which is run for each frame of the GIF.

##### renderFrame.done
**Only works for `terminalImage.gifBuffer` or `terminalImage.gifFile`**
Type: `() => void`\nDefault: [log-update](https://github.com/sindresorhus/log-update)\nCustom handler which is run when the animation playback is stopped.

Common options available for image rendering methods.

##### height
Type: `string | number`
Custom image height. Can be set as percentage or number of rows of the terminal. It is recommended to use the percentage options.

##### width
Type: `string | number`
Custom image width. Can be set as percentage or number of columns of the terminal. It is recommended to use the percentage options.

##### preserveAspectRatio
Type: `boolean`\nDefault: `true`\nWhether to maintain image aspect ratio or not.

##### preferNativeRender
Type: `boolean`\nDefault: `true`\nPrefer native terminal image protocols when available; set to false to force ANSI rendering.

Use terminalImage.file() to display an image from a file path. It returns a Promise that resolves to the ANSI escape codes required to render the image.

Options:

• width: (string | number) Custom width (percentage or columns).
• height: (string | number) Custom height (percentage or rows).
• preserveAspectRatio: (boolean) Whether to maintain aspect ratio. Defaults to true.
• preferNativeRender: (boolean) Prefer native terminal protocols if available; set to false to force ANSI rendering. Defaults to true.

import terminalImage from 'terminal-image';

console.log(await terminalImage.file('unicorn.jpg'));
console.log(await terminalImage.file('unicorn.jpg', {width: '50%', height: '50%'}));
console.log(await terminalImage.file('unicorn.jpg', {width: 50}));
console.log(await terminalImage.file('unicorn.jpg', {width: 70, height: 50, preserveAspectRatio: false}));

Use terminalImage.gifFile(filePath, options?) to play an animated GIF directly from a file path. It returns a cleanup function to stop the animation.

import terminalImage from 'terminal-image';

const stop = terminalImage.gifFile('path/to/animation.gif', {
	width: '50%'
});

// Stop the animation later
stop();

Use terminalImage.gifBuffer(buffer, options?) to play an animated GIF. This method returns a cleanup function that can be called to stop the animation.

Options:

• renderFrame: A function called for every frame. It receives the rendered frame data (as a string). This is often used with log-update to prevent flickering. Defaults to log-update.
• maximumFrameRate: The maximum frames per second for the animation. Defaults to 30.
• width: Target width.
• height: Target height.

Returns:

• A function that, when called, stops the animation and finalizes the rendering.

import terminalImage from 'terminal-image';
import fs from 'node:fs/promises';

const buffer = await fs.readFile('path/to/animation.gif');
const stop = terminalImage.gifBuffer(buffer, {
	width: '100%',
	height: '50%',
	maximumFrameRate: 24
});

// Later, to stop the animation:
stop();