PyModel/pythinker-code / .agents/skills/opentui
opentui
VerifiedBuild terminal UIs with OpenTUI. Covers core, components, audio, keymaps, React, Solid, plugins, testing, standalone executables, QR encoding, SSH, and Three.js WebGPU.
docs/bindings/react.mdx
View on GitHub---
title: React
description: Build terminal UIs with React and OpenTUI
order: 2
skill:
entry: true
intents: [react, jsx, hooks, keyboard, paste, focus, blur, selection, animation, testing]
---
# React bindings
Build terminal user interfaces using React with familiar patterns and components.
## Installation
Quick start with [bun](https://bun.sh) and [create-tui](https://github.com/msmps/create-tui):
```bash
bun create tui --template react
```
Manual installation:
```bash
bun install @opentui/react @opentui/core react
```
## Quick start
```tsx
import { createCliRenderer } from "@opentui/core"
import { createRoot } from "@opentui/react"
function App() {
return <text>Hello, world!</text>
}
const renderer = await createCliRenderer()
createRoot(renderer).render(<App />)
```
## TypeScript configuration
Configure your `tsconfig.json`:
```json
{
"compilerOptions": {
"lib": ["ESNext", "DOM"],
"target": "ESNext",
"module": "ESNext",
"moduleResolution": "bundler",
"jsx": "react-jsx",
"jsxImportSource": "@opentui/react",
"strict": true,
"skipLibCheck": true
}
}
```
## Runtime-loaded plugin support (if needed)
If your app loads external TS/TSX modules at runtime (for example a file-based plugin system), import this once in your app entry before dynamic imports:
```ts
import "@opentui/react/runtime-plugin-support"
```
Use this for both normal Bun runs and standalone compiled executables.
## Components
OpenTUI React provides JSX intrinsic elements that map to core renderables:
### Layout & display
- `<text>` - Text display with styling
- `<box>` - Container with borders and layout
- `<scrollbox>` - Scrollable container
- `<ascii-font>` - ASCII art text
- [`<TimeToFirstDraw />`](/docs/components/time-to-first-draw) - Exported first-draw performance timestamp component
QR code support is available from `@opentui/qrcode/react` and must be registered explicitly with `registerQRCode()`.
### Input
- `<input>` - Single-line text input
- `<textarea>` - Multi-line text input
- `<select>` - Selection list
- `<tab-select>` - Tab-based selection
### Code & diff
- `<code>` - Syntax-highlighted code
- `<line-number>` - Line numbers with diff/diagnostic support
- `<diff>` - Unified or split diff viewer
- `<markdown>` - Markdown rendering
### Text modifiers
Use inside `<text>` components:
- `<span>` - Inline styled text
- `<strong>`, `<b>` - Bold text
- `<em>`, `<i>` - Italic text
- `<u>` - Underlined text
- `<br>` - Line break
- `<a>` - Link text
## API reference
### `createRoot(renderer)`
Creates a React root for rendering into the terminal.
```tsx
import { createCliRenderer } from "@opentui/core"
import { createRoot } from "@opentui/react"
function App() {
return <text>Hello, React!</text>
}
const renderer = await createCliRenderer()
createRoot(renderer).render(<App />)
```
For plugin slots, see [Plugin Slots overview](/docs/plugins/slots) and [React slots](/docs/plugins/react).
## Hooks
### `useRenderer()`
Access the OpenTUI renderer instance.
```tsx
import { useRenderer } from "@opentui/react"
import { useEffect } from "react"
function App() {
const renderer = useRenderer()
useEffect(() => {
renderer.console.show()
console.log("Hello from console!")
}, [])
return <box />
}
```
### `useKeyboard(handler, options?)`
Handle keyboard events.
```tsx
import { useKeyboard, useRenderer } from "@opentui/react"
function App() {
const renderer = useRenderer()
useKeyboard((key) => {
if (key.name === "escape") {
renderer.destroy()
}
})
return <text>Press ESC to close</text>
}
```
To handle release events:
```tsx
useKeyboard(
(event) => {
if (event.eventType === "release") {
console.log("Key released:", event.name)
} else {
console.log("Key pressed:", event.name)
}
},
{ release: true },
)
```
### `useOnResize(callback)`
Handle terminal resize events.
```tsx
import { useOnResize } from "@opentui/react"
function App() {
useOnResize((width, height) => {
console.log(`Resized to ${width}x${height}`)
})
return <text>Resize-aware component</text>
}
```
### `useTerminalDimensions()`
Get reactive terminal dimensions.
```tsx
import { useTerminalDimensions } from "@opentui/react"
function App() {
const { width, height } = useTerminalDimensions()
return (
<text>
Terminal: {width}x{height}
</text>
)
}
```
### `usePaste(handler)`
Handle terminal paste events (bracketed paste).
```tsx
import { decodePasteBytes } from "@opentui/core"
import { usePaste } from "@opentui/react"
function App() {
usePaste((event) => {
const text = decodePasteBytes(event.bytes)
console.log("Pasted text:", text)
})
return <text>Paste something into the terminal</text>
}
```
### `useFocus(handler)`
Subscribe to terminal window focus events.
```tsx
import { useFocus } from "@opentui/react"
function App() {
useFocus(() => {
console.log("Terminal gained focus")
})
return <text>Focus-aware component</text>
}
```
### `useBlur(handler)`
Subscribe to terminal window blur events.
```tsx
import { useBlur } from "@opentui/react"
function App() {
useBlur(() => {
console.log("Terminal lost focus")
})
return <text>Blur-aware component</text>
}
```
### `useSelectionHandler(handler)`
Handle text selection events (e.g., mouse drag selection).
```tsx
import { useSelectionHandler } from "@opentui/react"
function App() {
useSelectionHandler((selection) => {
const text = selection.getSelectedText()
console.log("Selected:", text)
})
return <text selectable>Select this text with your mouse</text>
}
```
### `useTimeline(options?)`
Create and manage animations.
```tsx
import { useTimeline } from "@opentui/react"
import { useEffect, useState } from "react"
function App() {
const [width, setWidth] = useState(0)
const timeline = useTimeline({
duration: 2000,
loop: false,
})
useEffect(() => {
timeline.add(
{ width },
{
width: 50,
duration: 2000,
ease: "linear",
onUpdate: (animation) => {
setWidth(animation.targets[0].width)
},
},
)
}, [])
return <box style={{ width, backgroundColor: "#6a5acd" }} />
}
```
**Options:**
- `duration` - Animation duration in ms (default: 1000)
- `loop` - Whether to loop (default: false)
- `autoplay` - Auto-start (default: true)
- `onComplete` - Completion callback
- `onPause` - Pause callback
## Styling
Style components with props or the `style` prop:
```tsx
// Direct props
<box backgroundColor="blue" padding={2}>
<text>Hello</text>
</box>
// Style prop
<box style={{ backgroundColor: "blue", padding: 2 }}>
<text>Hello</text>
</box>
```
## Testing
`@opentui/react/test-utils` exports `testRender(node, options)`, a React-aware wrapper around [`createTestRenderer()`](/docs/core-concepts/testing). It mounts the initial node with React `act()`, returns the core `TestRendererSetup`, and unmounts the React root with `act()` when the renderer is destroyed.
```tsx
import { expect, test } from "bun:test"
import { testRender } from "@opentui/react/test-utils"
function App() {
return <text>Ready</text>
}
test("renders the application", async () => {
const setup = await testRender(<App />, { width: 20, height: 4 })
try {
await setup.renderOnce()
expect(setup.captureCharFrame()).toContain("Ready")
} finally {
setup.renderer.destroy()
}
})
```
The options argument is required and has the same type/default behavior as `TestRendererOptions`. The helper also enables React's act-environment flag for the mounted test root. On renderer destruction it unmounts the root, invokes any `options.onDestroy` callback, and then sets that flag to `false`. It does not preserve a previous global value, and a throwing `onDestroy` callback prevents the final reset.
`testRender()` does not return the React root or a separate rerender function. Use the returned core setup for frame capture, waits, resize, keyboard/mouse input, native stats, and external output. Always destroy the renderer in test teardown so the React tree unmounts and the global act-environment flag is reset.
## Example: Login form
```tsx
import { createCliRenderer } from "@opentui/core"
import { createRoot, useKeyboard } from "@opentui/react"
import { useCallback, useState } from "react"
function App() {
const [username, setUsername] = useState("")
const [password, setPassword] = useState("")
const [focused, setFocused] = useState<"username" | "password">("username")
const [status, setStatus] = useState("idle")
useKeyboard((key) => {
if (key.name === "tab") {
setFocused((prev) => (prev === "username" ? "password" : "username"))
}
})
const handleSubmit = useCallback(() => {
if (username === "admin" && password === "secret") {
setStatus("success")
} else {
setStatus("error")
}
}, [username, password])
return (
<box style={{ border: true, padding: 2, flexDirection: "column", gap: 1 }}>
<text fg="#FFFF00">Login Form</text>
<box title="Username" style={{ border: true, width: 40, height: 3 }}>
<input
placeholder="Enter username..."
onInput={setUsername}
onSubmit={handleSubmit}
focused={focused === "username"}
/>
</box>
<box title="Password" style={{ border: true, width: 40, height: 3 }}>
<input
placeholder="Enter password..."
onInput={setPassword}
onSubmit={handleSubmit}
focused={focused === "password"}
/>
</box>
<text fg={status === "success" ? "green" : status === "error" ? "red" : "#999"}>{status.toUpperCase()}</text>
</box>
)
}
const renderer = await createCliRenderer()
createRoot(renderer).render(<App />)
```
## Component extension
Register custom renderables as JSX elements:
```tsx
import { BoxRenderable, createCliRenderer, type BoxOptions, type RenderContext } from "@opentui/core"
import { createRoot, extend } from "@opentui/react"
class ConsoleButtonRenderable extends BoxRenderable {
private _label: string = "Button"
constructor(ctx: RenderContext, options: BoxOptions & { label?: string }) {
super(ctx, options)
if (options.label) this._label = options.label
this.borderStyle = "single"
this.padding = 2
}
get label(): string {
return this._label
}
set label(value: string) {
this._label = value
this.requestRender()
}
}
// Add TypeScript support
declare module "@opentui/react" {
interface OpenTUIComponents {
consoleButton: typeof ConsoleButtonRenderable
}
}
// Register the component
extend({ consoleButton: ConsoleButtonRenderable })
// Use in JSX
function App() {
return <consoleButton label="Click me!" style={{ border: true, backgroundColor: "green" }} />
}
const renderer = await createCliRenderer()
createRoot(renderer).render(<App />)
```
## React DevTools
OpenTUI React supports React DevTools for debugging:
1. Install:
```bash
bun add --dev react-devtools-core@7
```
2. Start DevTools:
```bash
npx react-devtools@7
```
3. Run with DEV flag:
```bash
DEV=true bun run your-app.ts
```
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |