Ink Component Export

Export your ASCII animations as self-contained React components for Ink, the library for building CLI apps with React.

Overview

Info

Ink export generates a TypeScript component that renders animated ASCII art directly in terminal applications.

The exported component:

Renders animation frame-by-frame in the terminal
Uses Ink's Text component with ANSI colors
Supports both dark and light terminal backgrounds
Includes optional playback API for programmatic control
Works with Ink 4.x and React 18+

Accessing Ink Export

Click Export in the toolbar

Select Ink Component from the format dropdown

Configure settings

Click Export to download

Ink Settings

Component File Name

Enter a name for your component file:

Automatically converts to kebab-case for filename
Generates PascalCase component name
Example: my-animation → my-animation.tsx with MyAnimation component

Color Mode

Choose the color format based on your target terminal's capabilities:

Option	Description
ANSI 16 (semantic)	Maps colors to the 16 standard ANSI colors. Maximum compatibility with all terminals, but limited color accuracy. Best for SSH sessions or legacy terminals.
xterm-256 (wide support)	Colors are clamped to the xterm-256 palette. Great balance of color fidelity and compatibility. Works in Terminal.app, iTerm2, Windows Terminal, and most modern terminals.
Hex colors (exact)	Uses exact hex color values for full 24-bit true color. Best color accuracy but requires terminal true color support.

Tip

Which should I choose?

Use ANSI 16 if you need to support older terminals or when colors should match the user's terminal theme
Use xterm-256 for the best balance of color fidelity and compatibility
Use Hex only when you know your users have terminals with true color support (iTerm2, Kitty, Alacritty, etc.)

All modes generate separate COLORS_DARK and COLORS_LIGHT (or THEME_DARK/THEME_LIGHT) dictionaries. The active palette is selected at runtime via the hasDarkBackground prop.

Loop Animation

Option	Behavior
Enabled	Animation loops continuously (default)
Disabled	Animation plays once and stops on last frame

Include Playback Controls

When enabled, the component exposes an API via the onReady callback:

tsx

<MyAnimation
  onReady={(api) => {
    api.play();      // Start playback
    api.pause();     // Pause playback
    api.restart();   // Restart from frame 0
    api.setFrame(5); // Jump to specific frame
  }}
/>

Output Structure

Generated TypeScript Component

tsx

import React, { useState, useEffect, useCallback, useRef } from 'react';
import { Text, Box } from 'ink';
 
// Dark terminal color palette
const COLORS_DARK: Record<string, string> = {
  c0: '#FF5733',
  c1: '#33FF57',
  // ... more colors
};
 
// Light terminal color palette  
const COLORS_LIGHT: Record<string, string> = {
  c0: '#CC4429',
  c1: '#29CC45',
  // ... adjusted for light backgrounds
};
 
// Animation data
const FRAME_DATA = [...];
 
interface AnimationAPI {
  play: () => void;
  pause: () => void;
  restart: () => void;
  setFrame: (frame: number) => void;
  isPlaying: () => boolean;
  getCurrentFrame: () => number;
  getFrameCount: () => number;
}
 
interface Props {
  hasDarkBackground?: boolean;
  autoPlay?: boolean;
  loop?: boolean;
  onReady?: (api: AnimationAPI) => void;
}
 
export const MyAnimation: React.FC<Props> = ({
  hasDarkBackground = true,
  autoPlay = true,
  loop = true,
  onReady,
}) => {
  // Component implementation...
};
 
export default MyAnimation;

Usage Instructions

After exporting, integrate the component into your Ink CLI application:

Download the exported .tsx file

Place it in your Ink project's source folder

Import and render in your CLI app

Basic Usage

tsx

import React from 'react';
import { render } from 'ink';
import { MyAnimation } from './my-animation';
 
// Simple render - auto-plays and loops
render(<MyAnimation />);

With Terminal Background Detection

tsx

import React from 'react';
import { render } from 'ink';
import { MyAnimation } from './my-animation';
 
// Detect terminal background or let user choose
const isDark = process.env.COLORFGBG?.includes('15;0') ?? true;
 
render(<MyAnimation hasDarkBackground={isDark} />);

With Playback Control

tsx

import React from 'react';
import { render } from 'ink';
import { MyAnimation, AnimationAPI } from './my-animation';
 
let animationApi: AnimationAPI;
 
render(
  <MyAnimation
    hasDarkBackground={true}
    autoPlay={false}
    loop={false}
    onReady={(api) => {
      animationApi = api;
      // Start after 2 seconds
      setTimeout(() => api.play(), 2000);
    }}
  />
);

Embedded in Larger CLI App

tsx

import React from 'react';
import { render, Box, Text } from 'ink';
import { MyAnimation } from './my-animation';
 
const App = () => (
  <Box flexDirection="column">
    <Text bold>Welcome to My CLI Tool</Text>
    <Box marginY={1}>
      <MyAnimation hasDarkBackground={true} />
    </Box>
    <Text dimColor>Press Ctrl+C to exit</Text>
  </Box>
);
 
render(<App />);

Component Props

Prop	Type	Default	Description
`hasDarkBackground`	`boolean`	`true`	Use dark or light color palette
`autoPlay`	`boolean`	`true`	Start playing immediately
`loop`	`boolean`	`true`	Loop animation continuously
`onReady`	`(api) => void`	-	Callback with playback API

API Methods

When onReady is provided, you receive an API object with these methods:

Method	Description
`play()`	Start or resume playback
`pause()`	Pause playback
`restart()`	Reset to frame 0 and play
`setFrame(n)`	Jump to specific frame
`isPlaying()`	Check if currently playing
`getCurrentFrame()`	Get current frame index
`getFrameCount()`	Get total number of frames

Color Modes Explained

Hex Mode

Generates exact hex color values organized into dark and light palettes:

tsx

const COLORS_DARK: Record<string, string> = {
  c0: '#9f29ff',  // Original color
  c1: '#04c7ff',
};
 
const COLORS_LIGHT: Record<string, string> = {
  c0: '#7f21cc',  // Adjusted for light backgrounds
  c1: '#03a0cc',
};

Best for: Terminal emulators with true color support (most modern terminals).

ANSI Mode

Maps colors to the standard ANSI 16 color palette:

tsx

const THEME_DARK: Record<string, string> = {
  c0: '13',  // bright magenta
  c1: '14',  // bright cyan
};
 
const THEME_LIGHT: Record<string, string> = {
  c0: '5',   // magenta
  c1: '6',   // cyan
};

Best for: Maximum compatibility across all terminals, respects user's terminal theme.

Tips

Use ANSI mode for CLI tools distributed to many users
Use Hex mode for internal tools or when exact colors matter
Set hasDarkBackground based on terminal detection or user preference
Disable autoPlay if you need to sync with other CLI elements
Enable loop for loading spinners and ambient animations

Troubleshooting

Colors Look Wrong

Check if your terminal supports true colors (for Hex mode)
Try ANSI mode for better compatibility
Verify hasDarkBackground matches your terminal theme

Animation Not Rendering

Ensure Ink 4.x is installed
Check that React 18+ is installed
Verify the import path is correct

Performance Issues

Reduce frame count in the original animation
Simplify the animation content
Consider reducing canvas size before export

Requirements

Node.js 16+
Ink 4.x
React 18+