Package Map

@visulima/tui is a single package with multiple entry points.

Use this page to decide which entry to import and where each API lives.

Quick Choice

@visulima/tui

The bare entry point — render, layout/measurement helpers, and other lower-level primitives. Components and hooks live on per-symbol subpaths (see @visulima/tui/components/<name> and @visulima/tui/hooks/<name> below).

Primary exports:

• render, renderToString
• primitives: MouseProvider, parseSgrMouse, processLayout, measureElement, applySelectionToStyledLine, clearOsc52, writeOsc52, …

npm install @visulima/tui react

import { render } from "@visulima/tui";

@visulima/tui/hooks/<name>

Every hook lives at its own subpath under @visulima/tui/hooks/<kebab-name>. This keeps the import graph small and makes it explicit which hook you depend on.

import { useAnimation } from "@visulima/tui/hooks/use-animation";
import { useFocus } from "@visulima/tui/hooks/use-focus";
import { useInput } from "@visulima/tui/hooks/use-input";
import { useTimer } from "@visulima/tui/hooks/use-timer";

Each subpath exports the hook as both a named export and a default export, plus its option/result types. Hook names map directly to their kebab-case subpath (useAnimation → use-animation, useFocusManager → use-focus-manager). The createLinkedScrollGroup factory lives at use-linked-scroll.

Breaking from earlier alphas. Hooks are no longer re-exported from the bare @visulima/tui entry — you must import each one from its own subpath.

@visulima/tui/components/<name>

Every component lives at its own subpath under @visulima/tui/components/<kebab-name>. This keeps the import graph small — you only pull in what you use, and heavy peer dependencies are loaded only when their component is imported.

import { Box } from "@visulima/tui/components/box";
import { Text } from "@visulima/tui/components/text";
import { Spinner } from "@visulima/tui/components/spinner";
import { TextInput } from "@visulima/tui/components/text-input";
import { ProgressBar } from "@visulima/tui/components/progress-bar";

Each subpath exports the component as both a named export and a default export, plus its *Props type. PascalCase component names map to kebab-case subpaths (BigText → big-text, SelectInput → select-input, TreeView → tree-view).

Breaking from earlier alphas. Components are no longer re-exported from the bare @visulima/tui entry — you must import each one from its own subpath.

Heavy component subpaths

A few components have large optional peer dependencies. Importing them via their subpath keeps your bundle small and makes the peer requirements explicit per component.

Install only what you need:

# BigText
npm install @visulima/tui react cfonts

# Code (and DiffView with syntax highlighting)
npm install @visulima/tui react shiki @shikijs/langs @shikijs/themes

# DiffView (without syntax highlighting)
npm install @visulima/tui react diff

# Markdown (with code block highlighting)
npm install @visulima/tui react marked shiki @shikijs/langs @shikijs/themes

# Table
npm install @visulima/tui react @visulima/tabular

Importing a heavy subpath without its peer dependencies installed will throw a module-not-found error at runtime.

React DevTools

Mounting the React DevTools overlay is opt-in and gated by the DEV=true environment variable. To enable it, install the optional peers:

npm install --save-dev react-devtools-core ws

DEV=true node ./my-app.js

When DEV is unset, neither react-devtools-core nor ws is loaded.

@visulima/tui/core

Framework-agnostic runtime backed by the Rust diff engine.

Primary APIs are exposed to TypeScript/JavaScript while rendering is handled by a native Rust diff engine.

Primary exports:

• Renderer
• TerminalGuard
• terminalSize
• Cell, StyleMasks
• InputParser
• TuiApp
• createInlineLoop

npm install @visulima/tui

import { Renderer, TerminalGuard, terminalSize } from "@visulima/tui/core";

@visulima/tui/react

Native React renderer — uses a Rust-backed diff engine for high-performance rendering.

Depends on @visulima/tui/core for terminal output and native diffing.

Primary exports:

• render, renderInline, renderToString
• components: Static, DevTools
• hooks: useInput, useApp, useFocus, useFocusManager, useMouse, useScrollable, useTextInput, useWindowSize, and more

Components (Box, Text, Spinner, etc.) are imported from their dedicated subpaths under @visulima/tui/components/<name> — the native renderer uses the same components.

npm install @visulima/tui react

import { Box } from "@visulima/tui/components/box";
import { Text } from "@visulima/tui/components/text";
import { render, useInput } from "@visulima/tui/react";

@visulima/tui/test

Framework-agnostic testing utilities for TUI components. Inspired by ink-testing-library and ink-testing.

Primary exports:

• render — render a component with mock streams, returns test instance with screen, keys, waitFor, flush
• cleanup — unmount all test instances (use in afterEach)
• createScreen — standalone screen query helpers with ANSI stripping
• createKeySender — standalone keyboard input simulator
• KEY — raw ANSI escape sequence constants for all common keys
• waitFor — standalone async polling assertion

import { render, cleanup, KEY, createScreen, createKeySender, waitFor } from "@visulima/tui/test";

Next Steps