CliRenderer - OpenTUI

Overview

The CliRenderer class is the core of OpenTUI’s rendering system. It manages the render loop, handles terminal I/O, processes user input, and provides the rendering context for all UI elements.

Creating a Renderer

createCliRenderer()

Creates and initializes a new CLI renderer instance.

async function createCliRenderer(config?: CliRendererConfig): Promise<CliRenderer>

config

CliRendererConfig

Configuration options for the renderer

CliRenderer

Promise<CliRenderer>

Returns a fully initialized renderer instance

Example

import { createCliRenderer } from "@opentui/core"

const renderer = await createCliRenderer({
  targetFps: 60,
  exitOnCtrlC: true,
  useMouse: true,
})

Configuration Options

CliRendererConfig

Configuration interface for renderer initialization.

stdin

NodeJS.ReadStream

Custom stdin stream (defaults to process.stdin)

stdout

NodeJS.WriteStream

Custom stdout stream (defaults to process.stdout)

remote

boolean

Enable remote terminal mode

testing

boolean

Enable testing mode (skips terminal setup)

exitOnCtrlC

boolean

default:true

Exit the process when Ctrl+C is pressed

exitSignals

NodeJS.Signals[]

Custom list of signals that trigger exit

forwardEnvKeys

string[]

Environment variables to forward to the renderer

debounceDelay

number

default:100

Debounce delay for resize events (in milliseconds)

targetFps

number

default:30

Target frames per second for rendering

maxFps

number

default:60

Maximum frames per second (caps render rate)

memorySnapshotInterval

number

Interval for taking memory snapshots (in milliseconds)

useThread

boolean

default:true

Use threading for render operations (disabled on Linux)

gatherStats

boolean

Collect rendering statistics

maxStatSamples

number

default:300

Maximum number of stat samples to keep

consoleOptions

ConsoleOptions

Configuration for the console overlay

postProcessFns

((buffer: OptimizedBuffer, deltaTime: number) => void)[]

Post-processing functions to apply after rendering

enableMouseMovement

boolean

default:true

Enable mouse movement events

useMouse

boolean

default:true

Enable mouse input

autoFocus

boolean

default:true

Automatically focus elements on mouse click

useAlternateScreen

boolean

default:true

Use alternate screen buffer

useConsole

boolean

default:true

Enable console overlay

experimental_splitHeight

number

Split screen mode height (experimental)

useKittyKeyboard

KittyKeyboardOptions | null

Kitty keyboard protocol options

backgroundColor

ColorInput

Background color for the renderer

openConsoleOnError

boolean

Automatically open console on uncaught errors

prependInputHandlers

((sequence: string) => boolean)[]

Input handlers to prepend to the handler chain

onDestroy

() => void

Callback invoked when the renderer is destroyed

Kitty Keyboard Protocol

KittyKeyboardOptions

Configuration for the Kitty keyboard protocol, which provides enhanced key event handling.

disambiguate

boolean

default:true

Disambiguate escape codes (fixes ESC timing, alt+key ambiguity, ctrl+c as event)

alternateKeys

boolean

default:true

Report alternate keys (numpad, shifted, base layout) for cross-keyboard shortcuts

events

boolean

default:false

Report event types (press/repeat/release)

allKeysAsEscapes

boolean

default:false

Report all keys as escape codes

reportText

boolean

default:false

Report text associated with key events

CliRenderer Class

Properties

root

RootRenderable

The root renderable element (container for all UI elements)

width

number

Current renderer width in terminal cells

height

number

Current renderer height in terminal cells

terminalWidth

number

Full terminal width (may differ from width in split mode)

terminalHeight

number

Full terminal height (may differ from height in split mode)

console

TerminalConsole

Console overlay instance for logging and debugging

keyInput

KeyHandler

Key input handler for keyboard events

isRunning

boolean

Whether the renderer is currently in a running state

isDestroyed

boolean

Whether the renderer has been destroyed

useMouse

boolean

Whether mouse input is enabled (can be set to toggle)

useConsole

boolean

Whether console overlay is enabled (can be set to toggle)

capabilities

any | null

Terminal capabilities detected from the terminal

resolution

PixelResolution | null

Terminal pixel resolution (if available)

themeMode

ThemeMode | null

Terminal theme mode (light/dark)

Methods

requestRender()

Request a render pass. The renderer will schedule a render based on the current FPS settings.

requestRender(): void

requestLive()

Request continuous rendering (starts the render loop).

requestLive(): void

dropLive()

Stop continuous rendering (stops the render loop).

dropLive(): void

start()

Explicitly start the renderer.

start(): void

pause()

Pause the renderer (can be resumed).

pause(): void

suspend()

Suspend the renderer (similar to pause but different state).

suspend(): void

resume()

Resume the renderer after pause/suspend.

resume(): void

idle()

Wait for the renderer to become idle (no pending renders).

idle(): Promise<void>

Promise<void>

Resolves when the renderer is idle

destroy()

Clean up and destroy the renderer. This should be called when shutting down.

destroy(): void

setBackgroundColor()

Set the background color for the renderer.

setBackgroundColor(color: ColorInput): void

color

ColorInput

Color value (hex string, RGBA object, or RGBA instance)

setCursorPosition()

Set the cursor position.

setCursorPosition(x: number, y: number, visible?: boolean): void

number

X coordinate (column)

number

Y coordinate (row)

visible

boolean

default:true

Whether the cursor should be visible

setCursorStyle()

Set the cursor style.

setCursorStyle(options: CursorStyleOptions): void

options

CursorStyleOptions

Cursor style options

setCursorColor()

Set the cursor color.

setCursorColor(color: RGBA): void

color

RGBA

RGBA color instance

setTerminalTitle()

Set the terminal window title.

setTerminalTitle(title: string): void

title

string

Terminal title text

toggleDebugOverlay()

Toggle the debug overlay (shows FPS, memory, etc.).

toggleDebugOverlay(): void

configureDebugOverlay()

Configure the debug overlay.

configureDebugOverlay(options: { enabled?: boolean; corner?: DebugOverlayCorner }): void

options.enabled

boolean

Enable or disable the overlay

options.corner

DebugOverlayCorner

Corner to display the overlay

addPostProcessFn()

Add a post-processing function to run after each render.

addPostProcessFn(processFn: (buffer: OptimizedBuffer, deltaTime: number) => void): void

processFn

(buffer: OptimizedBuffer, deltaTime: number) => void

Post-processing function

removePostProcessFn()

Remove a previously added post-processing function.

removePostProcessFn(processFn: (buffer: OptimizedBuffer, deltaTime: number) => void): void

addInputHandler()

Add an input handler to process raw terminal input sequences.

addInputHandler(handler: (sequence: string) => boolean): void

handler

(sequence: string) => boolean

Handler function that returns true if the sequence was handled

removeInputHandler()

Remove a previously added input handler.

removeInputHandler(handler: (sequence: string) => boolean): void

setFrameCallback()

Set a callback to run on each frame.

setFrameCallback(callback: (deltaTime: number) => Promise<void>): void

callback

(deltaTime: number) => Promise<void>

Async callback function

copyToClipboardOSC52()

Copy text to the system clipboard using OSC 52 escape sequence.

copyToClipboardOSC52(text: string, target?: ClipboardTarget): boolean

text

string

Text to copy

target

ClipboardTarget

Clipboard target (clipboard, primary, or secondary)

boolean

Whether the copy operation succeeded

Events

resize

Emitted when the terminal is resized.

renderer.on('resize', (width: number, height: number) => {
  console.log(`Terminal resized to ${width}x${height}`)
})

destroy

Emitted when the renderer is destroyed.

renderer.on('destroy', () => {
  console.log('Renderer destroyed')
})

focus

Emitted when the terminal gains focus.

renderer.on('focus', () => {
  console.log('Terminal focused')
})

blur

Emitted when the terminal loses focus.

renderer.on('blur', () => {
  console.log('Terminal blurred')
})

theme_mode

Emitted when the terminal theme mode changes.

renderer.on('theme_mode', (mode: 'light' | 'dark') => {
  console.log(`Theme changed to ${mode}`)
})

Mouse Events

MouseEvent

Represents a mouse event in the terminal.

type

MouseEventType

Event type: ‘down’, ‘up’, ‘move’, ‘drag’, ‘scroll’, ‘over’, ‘out’, ‘drop’, ‘drag-end’

button

number

Mouse button: 0 (left), 1 (middle), 2 (right), 4 (wheel up), 5 (wheel down)

number

X coordinate in terminal cells

number

Y coordinate in terminal cells

target

Renderable | null

The renderable that was clicked

modifiers

{ shift: boolean; alt: boolean; ctrl: boolean }

Modifier keys pressed during the event

scroll

ScrollInfo | undefined

Scroll information (for scroll events)

Methods

stopPropagation()

Stop the event from propagating to parent elements.

stopPropagation(): void

preventDefault()

Prevent the default action for this event.

preventDefault(): void

Core API

Text & Editing

Rendering

Input Handling

Layout

Advanced

​Overview

​Creating a Renderer

​createCliRenderer()

​Example

​Configuration Options

​CliRendererConfig

​Kitty Keyboard Protocol

​KittyKeyboardOptions

​CliRenderer Class

​Properties

​Methods

​requestRender()

​requestLive()

​dropLive()

​start()

​pause()

​suspend()

​resume()

​idle()

​destroy()

​setBackgroundColor()

​setCursorPosition()

​setCursorStyle()

​setCursorColor()

​setTerminalTitle()

​toggleDebugOverlay()

​configureDebugOverlay()

​addPostProcessFn()

​removePostProcessFn()

​addInputHandler()

​removeInputHandler()

​setFrameCallback()

​copyToClipboardOSC52()

​Events

​resize

​destroy

​focus

​blur

​theme_mode

​Mouse Events

​MouseEvent

​Methods

​stopPropagation()

​preventDefault()

Build docs developers (and LLMs) love

Overview

Creating a Renderer

createCliRenderer()

Example

Configuration Options

CliRendererConfig

Kitty Keyboard Protocol

KittyKeyboardOptions

CliRenderer Class

Properties

Methods

requestRender()

requestLive()

dropLive()

start()

pause()

suspend()

resume()

idle()

destroy()

setBackgroundColor()

setCursorPosition()

setCursorStyle()

setCursorColor()

setTerminalTitle()

toggleDebugOverlay()

configureDebugOverlay()

addPostProcessFn()

removePostProcessFn()

addInputHandler()

removeInputHandler()

setFrameCallback()

copyToClipboardOSC52()

Events

resize

destroy

focus

blur

theme_mode

Mouse Events

MouseEvent

Methods

stopPropagation()

preventDefault()