Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/sindresorhus/terminal-image
Display images in the terminal
https://github.com/sindresorhus/terminal-image
cli-utility image nodejs npm-package terminal-image
Last synced: 3 days ago
JSON representation
Display images in the terminal
- Host: GitHub
- URL: https://github.com/sindresorhus/terminal-image
- Owner: sindresorhus
- License: mit
- Created: 2018-05-08T16:14:22.000Z (over 6 years ago)
- Default Branch: main
- Last Pushed: 2024-07-26T14:06:13.000Z (6 months ago)
- Last Synced: 2024-10-29T15:29:18.465Z (3 months ago)
- Topics: cli-utility, image, nodejs, npm-package, terminal-image
- Language: JavaScript
- Size: 621 KB
- Stars: 975
- Watchers: 9
- Forks: 31
- Open Issues: 5
-
Metadata Files:
- Readme: readme.md
- License: license
Awesome Lists containing this project
- awesome-nodejs-cn - terminal-image - 在终端里展示图片 (包 / 命令行工具)
- awesome-nodejs - terminal-image - Display images in the terminal.  (Repository / Command-line Utilities)
- awesome-list - terminal-image
- awesome-nodejs - terminal-image - Display images in the terminal. (Packages / Command-line utilities)
- awesome-nodejs - terminal-image - Display images in the terminal - ★ 356 (Command-line utilities)
- awesome-node - terminal-image - Display images in the terminal. (Packages / Command-line utilities)
- awesome-nodejs-cn - terminal-image - 终端展示图片. (目录 / 命令行工具)
- awesome-nodejs-cn - terminal-image - **star:983** 在终端显示图像 (包 / 命令行实用工具)
README
# terminal-image
> Display images in the terminal
Works in any terminal that supports colors.
*In iTerm, the image will be [displayed in full resolution](screenshot-iterm.jpg), since iTerm has [special image support](https://www.iterm2.com/documentation-images.html).*
## Install
```sh
npm install terminal-image
```
## Usage
```js
import terminalImage from 'terminal-image';
console.log(await terminalImage.file('unicorn.jpg'));
```
Optionally, you can specify the `height` and/or `width` to scale the image. That can be either the percentage of the terminal window or number of rows and/or columns. Please note that the image will always be scaled to fit the size of the terminal. If width and height are not defined, by default the image will take the width and height of the terminal.
It is recommended to use the percentage option.
```js
import terminalImage from 'terminal-image';
console.log(await terminalImage.file('unicorn.jpg', {width: '50%', height: '50%'}));
```
You can set width and/or height as columns and/or rows of the terminal window as well.
```js
import terminalImage from 'terminal-image';
console.log(await terminalImage.file('unicorn.jpg', {width: 50}));
```
By default, aspect ratio is always maintained. If you don't want to maintain aspect ratio, set `preserveAspectRatio` to false. However, your image will be scaled to fit the size of the terminal.
```js
import terminalImage from 'terminal-image';
console.log(await terminalImage.file('unicorn.jpg', {width: 70, height: 50, preserveAspectRatio: false}));
```
## API
Supports PNG and JPEG images. Animated GIFs are also supported with `.gifBuffer` and `.gifFile`.
### terminalImage.buffer(imageBuffer, options?)
### terminalImage.file(filePath, options?)
Returns a `Promise` with the ANSI escape codes to display the image.
### terminalImage.gifBuffer(imageBuffer, options?)
### terminalImage.gifFile(filePath, options?)
Returns a function that can be called to stop the GIF animation.
#### options
Type: `object`
##### 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`\
Default: `true`
Whether to maintain image aspect ratio or not.
##### maximumFrameRate
**Only works for `terminalImage.gifBuffer` or `terminalImage.gifFile`**
Type: `number`\
Default: `30`
Maximum 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`\
Default: [log-update](https://github.com/sindresorhus/log-update)
Custom handler which is run for each frame of the GIF.
This can be set to change how each frame is shown.
##### renderFrame.done
**Only works for `terminalImage.gifBuffer` or `terminalImage.gifFile`**
Type: `() => void`\
Default: [log-update](https://github.com/sindresorhus/log-update)
Custom handler which is run when the animation playback is stopped.
This can be set to perform a cleanup when playback has finished.
## Tip
### Display a remote image
```js
import terminalImage from 'terminal-image';
import got from 'got';
const body = await got('https://sindresorhus.com/unicorn').buffer();
console.log(await terminalImage.buffer(body));
```
## Related
- [terminal-image-cli](https://github.com/sindresorhus/terminal-image-cli) - CLI for this module
- [terminal-link](https://github.com/sindresorhus/terminal-link) - Create clickable links in the terminal
- [chalk](https://github.com/chalk/chalk) - Style and color text in the terminal