OpenTUI Component Export

Export your ASCII animations as self-contained React components for OpenTUI, the framework for building terminal user interfaces with React.

Overview

Info

OpenTUI export generates a TypeScript component that renders animated ASCII art in terminal applications built with OpenTUI.

The exported component:

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

Accessing OpenTUI Export

Click Export in the toolbar

Select OpenTUI Component from the format dropdown

Configure settings

Click Export to download

OpenTUI 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 (as hex values). 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 color dictionaries for dark and light terminals. 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, View } from '@opentui/core';
 
// 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 OpenTUI application:

Download the exported .tsx file

Place it in your OpenTUI project's source folder

Import and render in your TUI app

Basic Usage

tsx

import { createCliRenderer } from '@opentui/core';
import { createRoot } from '@opentui/react';
import { MyAnimation } from './my-animation';
 
// Create renderer and render animation
const renderer = await createCliRenderer();
createRoot(renderer).render(<MyAnimation />);

With Terminal Background Configuration

tsx

import { createCliRenderer } from '@opentui/core';
import { createRoot } from '@opentui/react';
import { MyAnimation } from './my-animation';
 
const renderer = await createCliRenderer();
 
// Set based on terminal or user preference
createRoot(renderer).render(
  <MyAnimation hasDarkBackground={true} />
);

With Playback Control

tsx

import { createCliRenderer } from '@opentui/core';
import { createRoot } from '@opentui/react';
import { MyAnimation, AnimationAPI } from './my-animation';
 
let animationApi: AnimationAPI;
 
const renderer = await createCliRenderer();
createRoot(renderer).render(
  <MyAnimation
    hasDarkBackground={true}
    autoPlay={false}
    loop={false}
    onReady={(api) => {
      animationApi = api;
      // Control playback programmatically
      setTimeout(() => api.play(), 1000);
    }}
  />
);

Embedded in Larger TUI App

tsx

import { createCliRenderer } from '@opentui/core';
import { createRoot } from '@opentui/react';
import { View, Text } from '@opentui/core';
import { MyAnimation } from './my-animation';
 
const App = () => (
  <View flexDirection="column">
    <Text bold>My TUI Application</Text>
    <View marginY={1}>
      <MyAnimation hasDarkBackground={true} />
    </View>
    <Text dim>Press q to quit</Text>
  </View>
);
 
const renderer = await createCliRenderer();
createRoot(renderer).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.

Comparing to Ink Export

Feature	OpenTUI	Ink
Framework	OpenTUI	Ink
Component syntax	Similar React	React
Renderer	`createCliRenderer`	`render()`
Import style	`@opentui/core`	`ink`
Color support	Hex + ANSI	Hex + ANSI

Both exports produce similar React components. Choose based on which terminal UI framework your project uses.

Tips

Use ANSI mode for CLI tools distributed to many users
Use Hex mode when exact color reproduction matters
Set hasDarkBackground based on user preference or terminal detection
Disable autoPlay when you need to coordinate with other UI elements
Enable loop for loading indicators 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 OpenTUI is properly 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+
OpenTUI
React 18+