ink-picture

Better image component for Ink CLI/TUI applications.

Display images in your terminal with automatic protocol detection and graceful fallbacks. Supports Sixel, Kitty image protocol, iTerm2 inline images, ASCII art, and more!

Who's using ink-picture?

• Instagram CLI: CLI and terminal client for Instagram

Feel free to open a PR to showcase your project here!

Installation

npm install ink-picture

Quick Start

import React from "react";
import { Box, render } from "ink";
import Image, { InkPictureProvider } from "ink-picture";

function App() {
  return (
    <InkPictureProvider>
      <Image
        src="https://picsum.photos/200/200"
        width={20}
        height={10}
        alt="Example image"
      />
    </InkPictureProvider>
  );
}

render(<App />);

Usage

<Image />

Drop-in image component with dynamic rendering protocol selection. This component can display images using multiple rendering methods depending on the terminal environment.

<Image src="path/to/image.png" />
<Image src="https://picsum.photos/200/200" />
<Image src="file:///path/to/image.jpg" />

<Image
  src="path/to/image.png"
  width={10}
  height={5}
/>

// Image dimensions will be 12W X 8H
<Box width={20} height={10}>
  <Image
    src="path/to/image.png"
    width="60%"
    height="80%"
  />
</Box>

// Height will default to "100%"
<Image
  src="path/to/image.png"
  width={10}
/>

// This will not work because parent size is unbounded
<Box>
  <Image
    src="path/to/image.png"
    width="100%"
    height="100%"
  />
</Box>

<Image src="path/to/image.png" alt="a close-up shot of a red brick house" />

// Image will be rendered with sixels when fully visible,
// and skip rendering altogether otherwise.
<Image
  src="path/to/image.png"
  protocol="sixel"
/>

// Image will be rendered with kitty graphics protocol when fully visible,
// and fall back to a text-based protocol otherwise.
<Image
  src="path/to/image.png"
  protocol={{ "full": "kitty" }}
/>

<InkPictureProvider />

Wrapper component that Detects and provides terminal capabilities, as well as configuration and image caching to all descendant Image components.

TerminalInfoProvider is exported as an alias for InkPictureProvider for backwards compatibility.

Upon mounting, the provider queries the terminal for capabilities using escape sequences. This temporarily intercepts stdin for up to 1 second (usually much shorter). Any user keystrokes made during this window are safely buffered and re-injected into your app once detection completes.

<InkPictureProvider
  config={{ cacheSize: 20 }}
  onTerminalInfoDetection={(info) => {
    foo(info);
  }}
>
  <App />
</InkPictureProvider>

Individual components for each protocol

Each rendering protocol has a standalone component export. They all accept the same ImageProps (src, width, height, alt) and can be used directly when you want more low-level control:

import {
  AsciiImage,
  BrailleImage,
  HalfBlockImage,
  SixelImage,
  KittyImage,
  ITerm2Image,
} from "ink-picture";

All protocol components must still be wrapped in <InkPictureProvider>. They only handle visibility detection by checking against app and terminal viewport dimensions.

See Protocols for differences between each component.

Hooks

The following hooks are also exported for use in custom components:

• useInkPictureConfig(): returns the resolved InkPictureConfig combining defaults and overrides
• useTerminalInfo(): returns the resolved TerminalInfo combining defaults, detected terminal info, and overrides.
• useImageCache(): returns the image cache instance (or null if caching is disabled)

If useTerminalInfo() is used outside of an InkPictureProvider, the following defaults will be used. Image rendering quality may degrade significantly with the default values; they are only meant to be a safe fallback.

Rendering protocols

Images can be rendered using one of the following protocols:

Compatibility with terminal emulators

ink-picture should work out-of-the-box in most terminal emulators and select the best supported protocol. Yet, terminal emulators may lack support for certain protocols and/or have non-compliant or faulty implementations for some protocols.

Use the table below as a reference to check which protocol to use for your terminal. You might also want to install a better terminal emulator for best experience.

✅ = Fully supported
⚠️ = Partially supported (works but may have issues or caveats)
❌ = Not supported

Please refer to Are We Sixel Yet? for a comprehensive (but slightly out-of-date) list of terminals that support Sixel graphics.

If you know your terminal emulator supports any of the above protocols but is not listed here, please open an issue or PR to update the table.

Protocol selection

When no protocol prop is specified, Image selects the best protocol automatically:

1. A graphical protocol (kitty > iTerm2 > Sixel, in that order) is chosen for fully visible images if the terminal supports it. The priority order is adjusted per-terminal to avoid known issues (see the heuristic in getBestProtocol).
2. If no graphical protocol is supported, a text-based protocol is used instead: halfBlock when both Unicode and color are available, braille when only Unicode is available, or ascii as the universal fallback.
3. When an image is partially or entirely outside the app or terminal viewport, it dynamically switches to a text-based protocol to avoid image dislocation.

Visibility

Each Image component tracks its absolute position in the terminal and determines whether it is fully visible, partially visible, or hidden relative to the terminal viewport and the app bounds. This drives the automatic protocol switching described above.

You can customize visibility detection with the getVisibility callback:

<Image
  src="image.png"
  getVisibility={({
    position,
    terminalWidth,
    terminalHeight,
    defaultVisibility,
  }) => {
    // Custom logic, e.g. account for a sticky header that overlaps the image
    if (position.row < 5) return "partial";
    return defaultVisibility;
  }}
/>

The callback receives a VisibilityInfo object:

The useVisibility hook and usePosition hook are also exported if you need visibility logic in custom components.

Screen reader accessibility

When Ink's screen reader mode is active, Image renders an empty Box with an aria-label describing the image. The label is either the alt prop or the image source string. Image data is not loaded or rendered, keeping output clean for screen readers.

Configuration

Configuration can be set through the config prop on <InkPictureProvider> or via environment variables. Environment variables take precedence over prop values.

Contributing

Contributions are welcome! To contribute:

1. Open or comment on an issue describing what you want to change
2. Fork the repository
3. Create a feature branch: git checkout -b feature/amazing-feature
4. Install dependencies: pnpm install
5. Make your changes
6. Run tests: pnpm test
7. Open a pull request

License

MIT