@effect-tui/react

React renderer for terminal UIs with spring animations.

Installation

``bash
bun add @effect-tui/react @effect-tui/core effect react
`

Quick Start

`tsx
// tsconfig.json: { "compilerOptions": { "jsxImportSource": "@effect-tui/react" } }

import { render, useQuit, useShortcut } from "@effect-tui/react"

function App() {
const [count, setCount] = useState(0)

const quit = useQuit()
useShortcut({
q: () => quit(),
space: () => setCount((c) => c + 1),
})

return (

Count: {count}
Press space to increment, q to quit

)
}

render()
`

Dev / HMR

Enable hot reload by passing dev: true and importMeta:

`tsx
export default function App() { ... }

render(, { dev: true, importMeta: import.meta })
`

Note: When dev: true, the entry module's default export is re-imported
on each change. Keep your app as the default export for reliable HMR.

JSX Elements

- - Vertical flex layout
- - Horizontal flex layout
- - Text with optional fg/bg colors
- - Container with optional border
- - Imperative drawing API
- - Flexible space

Canvas draw context:
- text(x, y, str, style?)
- fillRect(x, y, w, h, char?, style?)
- box(x, y, w, h, opts?)
- clear()
- style(style?) → style id for reuse
- cell(x, y, cp, style?, width?)
- cells(cells[])

Hooks

- useKeyboard(callback) - Handle keyboard input
- useShortcut(shortcuts, options?) - Map key strings to handlers
- usePaste(callback) - Handle bracketed paste events (callback receives { text, preventDefault? })
- useQuit() - Request a clean exit (restores terminal state)
- useTerminalSize() - Get terminal dimensions (re-renders on resize)
- useSpring(initial, options) - Spring animation
- useSprings(count, fn) - Multiple springs
- useColorSpring(color, options) - Animate colors

Components

- TextInput - Single-line input (pasting inserts normalized text)
- MultilineTextInput - Multi-line input (pasting preserves newlines)

Spring Animations

`tsx
import { useSpring, useSpringRenderer, useRenderer } from "@effect-tui/react"

function AnimatedBox() {
const renderer = useRenderer()
useSpringRenderer(renderer)

const [xMv, setX] = useSpring(0, { visualDuration: 0.35 })

useKeyboard((key) => {
if (key.name === "right") setX(20)
if (key.name === "left") setX(0)
})

return (
{
ctx.box(xMv.get(), 0, 10, 5, { border: "rounded" })
}} />
)
}
`

Architecture

Each frame (60fps default):
1. Measure - Host tree calculates sizes bottom-up
2. Layout - Host tree assigns positions top-down
3. Render - Each host writes to CellBuffer
4. Diff - Compare with previous buffer, find changed lines
5. Write - Single stdout.write() with ANSI sequences

`
React JSX → Reconciler → Host Tree → CellBuffer → Terminal
`

Testing

Use renderTUI() for integration tests:

`tsx
import { renderTUI } from "@effect-tui/react/test"

it("renders and handles input", () => {
const { lastFrame, sendKey, renderNow, unmount } = renderTUI()

expect(lastFrame()).toContain("Count: 0")

sendKey({ name: "up" })
renderNow()

expect(lastFrame()).toContain("Count: 1")
unmount()
})
`

API

$3

- createRenderer(options?) - Create renderer instance
- createRoot(renderer) - Create React root
- render(element, options?) - One-liner convenience API

$3

importMeta is required whenever you pass the options object.

`ts
type RenderOptions = RendererOptions & {
dev?: boolean
importMeta: ImportMetaLike
}

interface RendererOptions {
fps?: number // Default: 60
mode?: "fullscreen" | "inline"
exitOnCtrlC?: boolean // Default: true
handleSignals?: boolean // Default: true (signals + process exit cleanup)
manualMode?: boolean // For testing
}
`

Environment Variables

- PROFILE_TUI=1 - Enable profiling (writes to tui-profile.txt)
- EFFECT_TUI_EDITOR / EDITOR` - Editor for trace visualization

License

MIT