@effect-tui/react

React renderer for terminal UIs with spring animations.

Installation

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

Quick Start

// 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 (
    <vstack>
      <text>Count: {count}</text>
      <text fg="gray">Press space to increment, q to quit</text>
    </vstack>
  )
}

render(<App />)

Dev / HMR

Enable hot reload by passing dev: true and importMeta:

export default function App() { ... }

render(<App />, { 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

• <vstack> - Vertical flex layout
• <hstack> - Horizontal flex layout
• <text> - Text with optional fg/bg colors
• <box> - Container with optional border
• <canvas> - Imperative drawing API
• <spacer> - 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

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 (
    <canvas draw={(ctx) => {
      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:

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

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

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

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

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

API

Renderer

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

Options

importMeta is required whenever you pass the options object.

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