CliRenderer

Core renderer class for managing terminal UI rendering, input handling, and lifecycle

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> · 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

x · number

X coordinate (column)

y · 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 · 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)

x · number

X coordinate in terminal cells

y · 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