# term-img

**Repository Path**: mirrors_sindresorhus/term-img

## Basic Information

- **Project Name**: term-img
- **Description**: Display images in iTerm
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2020-08-19
- **Last Updated**: 2026-05-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# term-img

> Display images in terminals using the iTerm inline image protocol

You probably want the higher-level [`terminal-image`](https://github.com/sindresorhus/terminal-image) package for displaying your images.

![](screenshot.jpg)

Even [animated gifs](https://github.com/vdemedes/gifi)!

*Currently only supported on [iTerm >=3](https://www.iterm2.com/downloads.html), [WezTerm](https://wezfurlong.org/wezterm/), [Konsole](https://konsole.kde.org/), [Rio](https://rioterm.com/), and [VSCode integrated terminal](https://code.visualstudio.com/).*

## Install

```sh
npm install term-img
```

## Usage

```js
import terminalImage from 'term-img';

function fallback() {
	// Return something else when not supported
}

console.log(terminalImage('unicorn.jpg', {fallback}));
```

## API

### terminalImage(image, options?)

Get the image as a `string` that you can log manually.

#### image

Type: `string | Uint8Array`

File path to an image or an image as a buffer.

#### options

Type: `object`

##### width
##### height

Type: `'auto' | string | number`

The width and height are given as a number followed by a unit, or the word `'auto'`.

- `N`: N character cells.
- `Npx`: N pixels.
- `N%`: N percent of the session's width or height.
- `auto`: The image's inherent size will be used to determine an appropriate dimension.

##### preserveAspectRatio

Type: `boolean`\
Default: `true`

##### fallback

Type: `Function`\
Default: `() => throw new UnsupportedTerminalError()`

Enables you to do something else when the terminal doesn't support images.

## Related

- [term-img-cli](https://github.com/sindresorhus/term-img-cli) - CLI for this module
- [term-kitty-img](https://github.com/tbjgolden/term-kitty-img) - Similar package but for Kitty, Konsole, WezTerm