Getting Started
Install @visulima/tui and choose the right rendering mode for your project
Getting Started
@visulima/tui supports three runtime modes.
| Mode | Primary API | Import path | Best for |
|---|---|---|---|
| React mode | render(<App />) | @visulima/tui/react | Component-driven TUIs with hooks and Yoga layout |
| Raw-buffer mode | Renderer + renderer.render | @visulima/tui/core | Direct per-cell rendering and custom loops |
| Inline mode | renderInline / createInlineLoop | @visulima/tui/react / @visulima/tui/core | Fixed-height UI below the cursor |
| Testing | render / cleanup / screen / keys / waitFor / flush | @visulima/tui/test | Test components with mock streams, no real terminal |
Install
React apps (most users)
npm install @visulima/tui react react-reconcilerRaw-buffer / non-React apps
npm install @visulima/tui
@visulima/tui/coreis a TypeScript-facing runtime with a native Rust diff/render engine. React is an optional peer dependency.
Component imports
Every component is published at its own subpath under @visulima/tui/components/<kebab-name>. Hooks, render, and primitives stay on the bare @visulima/tui entry.
import { Box } from "@visulima/tui/components/box";
import { Text } from "@visulima/tui/components/text";
import { Spinner } from "@visulima/tui/components/spinner";
import { useApp } from "@visulima/tui/hooks/use-app";
import { useInput } from "@visulima/tui/hooks/use-input";
import { render } from "@visulima/tui";This means you only pull in the components you actually use, and heavy peer dependencies stay tree-shakeable.
Breaking from earlier alphas. Components are no longer re-exported from the bare
@visulima/tuientry — you must import each one from its own subpath.
Optional peer dependencies
A few components have heavy peer dependencies. Install only the peers for the components you actually use:
| Component | Subpath | Required peers |
|---|---|---|
BigText | @visulima/tui/components/big-text | cfonts |
Code | @visulima/tui/components/code | shiki, @shikijs/langs, @shikijs/themes |
DiffView | @visulima/tui/components/diff-view | diff (+ shiki, @shikijs/langs, @shikijs/themes for syntax highlighting) |
Markdown | @visulima/tui/components/markdown | marked (+ shiki, @shikijs/langs, @shikijs/themes for code blocks; @visulima/tabular for tables) |
Table | @visulima/tui/components/table | @visulima/tabular |
To enable the React DevTools overlay (DEV=true), install the optional peers react-devtools-core and ws.
See Package Map › Heavy component subpaths for full installation snippets.
Requirements
- Node.js: 20.19 or higher
Run examples in this repository
# React mode
node --import @oxc-node/core/register examples/kitchen-sink.tsx
node --import @oxc-node/core/register examples/counter.tsx
# Raw-buffer mode
node --import @oxc-node/core/register examples-raw/matrix.ts
node --import @oxc-node/core/register examples-raw/conway.ts
# Inline mode (React)
node --import @oxc-node/core/register examples/inline-minimal.tsxSee Examples for the full list.
Ink migration (typical)
- import { render, Box, Text } from 'ink'
+ import { render } from '@visulima/tui'
+ import { Box } from '@visulima/tui/components/box'
+ import { Text } from '@visulima/tui/components/text'Most app-level API usage maps directly. See Ink Compatibility for caveats and stubs.