Ink Picture Component

1.3.5 · active · verified Wed Apr 22

ink-picture is an actively maintained Ink component designed for rendering images within CLI/TUI applications, providing a robust alternative to less feature-rich or unmaintained libraries. Currently at version 1.3.5, the library receives regular updates, including dependency bumps, bug fixes, and new features like partial image loading and support for advanced terminal graphics protocols. It intelligently detects terminal capabilities, supporting Kitty, iTerm2, Sixel, Half-block, Braille, and ASCII art, with graceful fallbacks. Its key differentiator is the automatic and prioritized protocol detection, ensuring the best possible image quality for the user's terminal, and its continuous development compared to dormant alternatives. The package requires Node.js >=18 and peer dependencies of Ink >=5 and React >=18.

Common errors

```
Error: Could not find 'TerminalInfoProvider' context. Make sure you wrap your app with <TerminalInfoProvider>
```
cause The `Image` component was rendered without being nested inside a `TerminalInfoProvider` component.

fix Wrap your root Ink component, or at least the section containing `Image` components, with `<TerminalInfoProvider>`.
```
TypeError: (0 , ink_picture_1.Image) is not a function or TypeError: Image is not a constructor
```
cause Attempting to import `Image` as a named export (`import { Image } from 'ink-picture'`) when it is the default export.

fix Change your import statement to `import Image, { TerminalInfoProvider } from 'ink-picture'` to correctly import `Image` as the default export.
```
SyntaxError: Named export 'TerminalInfoProvider' not found. The requested module 'ink-picture' does not provide an export named 'TerminalInfoProvider'
```
cause Attempting to import `TerminalInfoProvider` as a default export (`import TerminalInfoProvider from 'ink-picture'`) when it is a named export.

fix Change your import statement to `import { TerminalInfoProvider } from 'ink-picture'` (or `import Image, { TerminalInfoProvider } from 'ink-picture'`) to correctly import `TerminalInfoProvider` as a named export.
```
ERR_REQUIRE_ESM
```
cause Attempting to `require()` the `ink-picture` package in a CommonJS environment, but it is an ESM-only package.

fix Ensure your project is configured for ESM (e.g., `"type": "module"` in `package.json`) and use `import` statements instead of `require()`.

Warnings

gotcha All `Image` components must be wrapped within a `TerminalInfoProvider`. Failure to do so will result in runtime errors or incorrect rendering as terminal capabilities cannot be detected.
Fix: Ensure your Ink component tree, or at least the part containing `<Image>` components, is wrapped with `<TerminalInfoProvider>`.
breaking The package requires Node.js version 18 or higher. Older Node.js versions are not supported.
Fix: Upgrade your Node.js environment to version 18 or newer.
breaking This library has peer dependencies on `ink` (version >=5) and `react` (version >=18). Using older versions may lead to compatibility issues or errors.
Fix: Ensure `ink` and `react` are installed at their specified minimum versions: `npm install ink@"^5" react@"^18"`.
gotcha The `protocol` prop for the `Image` component was typed as a generic `string` prior to v1.3.2. Since v1.3.2, it is a literal union type of supported protocols (e.g., `'auto' | 'ascii' | 'braille' | 'halfBlock' | 'sixel' | 'iterm2' | 'kitty'`), improving TypeScript developer experience.
Fix: Update your codebase to leverage the specific literal union types for the `protocol` prop for better type safety and autocompletion.
gotcha The `allowPartial` prop was introduced in v1.3.4, allowing partially loaded images to render. This behavior is disabled by default.
Fix: If you need to display images before they are fully loaded, explicitly set `allowPartial={true}` on the `Image` component.

Install

npm install ink-picture npm
yarn add ink-picture yarn
pnpm add ink-picture pnpm

Imports

Image
wrong:
```
import { Image } from 'ink-picture'
```
correct:
```
import Image, { TerminalInfoProvider } from 'ink-picture'
```
`Image` is the default export of the package, bundled with named exports like `TerminalInfoProvider`. Do not use a named import for `Image` itself.
TerminalInfoProvider
wrong:
```
import TerminalInfoProvider from 'ink-picture'
```
correct:
```
import { TerminalInfoProvider } from 'ink-picture'
```
`TerminalInfoProvider` is a named export and must be imported with curly braces.
TerminalInfoProvider (Type)
wrong:
```
import { TerminalInfoProviderProps } from 'ink-picture'
```
correct:
```
import type { TerminalInfoProviderProps } from 'ink-picture'
```
When importing types, use `import type` for clarity and better tree-shaking with modern bundlers. The specific type name for protocol names introduced in v1.3.2 is not explicitly documented but can be inferred or checked in `.d.ts` files.

Quickstart

This example demonstrates the basic setup for `ink-picture`, rendering an image from a URL within an Ink application, wrapped in the required `TerminalInfoProvider`.

import React from 'react';
import { Box, render } from 'ink';
import Image, { TerminalInfoProvider } from 'ink-picture';

function App() {
  return (
    <TerminalInfoProvider>
      <Box flexDirection="column">
        <Image
          src="https://placehold.co/400x200.png?text=Hello+Ink"
          width={40}
          height={20}
          alt="Example image"
        />
      </Box>
    </TerminalInfoProvider>
  );
}

render(<App />);

view raw JSON →