ink-picture

library1.3.5jsnpmunverified

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.

web-framework

npm install ink-picture

github ↗package ↗

INSTALL

IMPORT

SIG · INK-PICTURE

ink-picture

web-frameworkjavascriptv1.3.5

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Image

✓ import Image, { TerminalInfoProvider } from 'ink-picture'

✗ import { Image } 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

✓ import { TerminalInfoProvider } from 'ink-picture'

✗ import TerminalInfoProvider from 'ink-picture'

`TerminalInfoProvider` is a named export and must be imported with curly braces.

TerminalInfoProvider (Type)

✓ import type { TerminalInfoProviderProps } from 'ink-picture'

✗ import { 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.

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 />);

Debug

Known issues

gotchaAll `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>`.

affects: >=1.0.0

breakingThe 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.

affects: >=1.0.0

breakingThis 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"`.

affects: >=1.0.0

fix

Update your codebase to leverage the specific literal union types for the `protocol` prop for better type safety and autocompletion.

affects: >=1.3.2

gotchaThe `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.

affects: >=1.3.4

Errors

Common errors & fixes

Error: Could not find 'TerminalInfoProvider' context. Make sure you wrap your app with <TerminalInfoProvider>

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

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'

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

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()`.

Upgrade

Version history

1.3.5latest on npm

Audit

Dependencies

inkrequiredPeer dependency for Ink CLI/TUI applications.

reactrequiredPeer dependency for React components in Ink.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/endernoke/ink-picture ↗

packagehttps://www.npmjs.com/package/ink-picture ↗