Opentui React

OpenTUI React Integration

Expert assistance for building terminal UIs with OpenTUI and React.

Quick Start

# Install dependencies
bun install @opentui/core @opentui/react react

Basic Setup

import { createCliRenderer } from "@opentui/core"
import { createRoot } from "@opentui/react"

function App() {
  return <text>Hello, OpenTUI React!</text>
}

async function main() {
  const renderer = await createCliRenderer()
  createRoot(renderer).render(<App />)
}

main()

React Hooks

useKeyboard

Handle keyboard events in React components.

import { useKeyboard } from "@opentui/react"

function App() {
  useKeyboard((key) => {
    if (key.name === "c" && key.ctrl) {
      process.exit(0)
    }
    if (key.name === "q") {
      process.exit(0)
    }
  })

  return <text>Press Ctrl+C or q to exit</text>
}

useRenderer

Access the renderer instance.

import { useRenderer } from "@opentui/react"

function Component() {
  const renderer = useRenderer()

  const handleClick = () => {
    console.log("Renderer available:", !!renderer)
  }

  return <box onClick={handleClick}>Click me</box>
}

useTerminalDimensions

Get terminal size changes.

import { useTerminalDimensions } from "@opentui/react"

function Responsive() {
  const { width, height } = useTerminalDimensions()

  return (
    <box>
      <text>Terminal: {width}x{height}</text>
    </box>
  )
}

useTimeline

Create animations in React.

import { useTimeline } from "@opentui/react"
import { useRef } from "react"

function AnimatedBox() {
  const boxRef = useRef<any>(null)

  const timeline = useTimeline({
    duration: 1000,
    easing: (t) => t * (2 - t), // easeOutQuad
  })

  const animate = () => {
    if (boxRef.current) {
      timeline.to(boxRef.current, {
        backgroundColor: { r: 255, g: 0, b: 0 },
      })
      timeline.play()
    }
  }

  return (
    <box ref={boxRef} onClick={animate}>
      <text>Click to animate</text>
    </box>
  )
}

React Components

All OpenTUI components are available as JSX elements:

import {
  text,
  box,
  input,
  select,
  scrollbox,
  code,
} from "@opentui/react"

function Form() {
  return (
    <box flexDirection="column" gap={1}>
      <text decoration="bold">User Information</text>

      <input placeholder="Name" />
      <input placeholder="Email" />

      <select
        options={[
          { label: "Option 1", value: "1" },
          { label: "Option 2", value: "2" },
        ]}
      />

      <box borderStyle="single">
        <text>Submit</text>
      </box>
    </box>
  )
}

Styling in React

Styles are passed as props to components:

function StyledComponent() {
  return (
    <box
      borderStyle="double"
      borderColor={{ r: 100, g: 149, b: 237 }}
      backgroundColor={{ r: 30, g: 30, b: 30 }}
      padding={1}
    >
      <text
        foregroundColor={{ r: 255, g: 255, b: 255 }}
        decoration="bold underline"
      >
        Styled Text
      </text>
    </box>
  )
}

Color format: { r: number, g: number, b: number, a?: number }

State Management

Local State

import { useState } from "react"

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

  useKeyboard((key) => {
    if (key.name === "up") setCount(c => c + 1)
    if (key.name === "down") setCount(c => c - 1)
  })

  return (
    <box>
      <text>Count: {count}</text>
      <text>Use arrow keys</text>
    </box>
  )
}

Form State

function LoginForm() {
  const [email, setEmail] = useState("")
  const [password, setPassword] = useState("")
  const [errors, setErrors] = useState<any>({})

  const handleSubmit = () => {
    const newErrors: any = {}

    if (!email.includes("@")) {
      newErrors.email = "Invalid email"
    }
    if (password.length < 8) {
      newErrors.password = "Password too short"
    }

    if (Object.keys(newErrors).length > 0) {
      setErrors(newErrors)
      return
    }

    console.log("Login:", { email, password })
  }

  return (
    <box flexDirection="column" gap={1}>
      <text decoration="bold">Login</text>

      <input
        value={email}
        onChange={setEmail}
        placeholder="Email"
      />
      {errors.email && (
        <text foregroundColor={{ r: 231, g: 76, b: 60 }}>
          {errors.email}
        </text>
      )}

      <input
        value={password}
        onChange={setPassword}
        placeholder="Password"
        password
      />
      {errors.password && (
        <text foregroundColor={{ r: 231, g: 76, b: 60 }}>
          {errors.password}
        </text>
      )}

      <box onClick={handleSubmit} borderStyle="single">
        <text>Submit</text>
      </box>
    </box>
  )
}

External State Management

Redux Integration

import { Provider, useSelector, useDispatch } from "react-redux"

function Counter() {
  const count = useSelector((state: any) => state.count)
  const dispatch = useDispatch()

  useKeyboard((key) => {
    if (key.name === "up") dispatch({ type: "INCREMENT" })
    if (key.name === "down") dispatch({ type: "DECREMENT" })
  })

  return <text>Count: {count}</text>
}

Zustand Integration

import { create } from "zustand"

const useStore = create((set) => ({
  count: 0,
  increment: () => set((state: any) => ({ count: state.count + 1 })),
  decrement: () => set((state: any) => ({ count: state.count - 1 })),
}))

function Counter() {
  const { count, increment, decrement } = useStore()

  useKeyboard((key) => {
    if (key.name === "up") increment()
    if (key.name === "down") decrement()
  })

  return <text>Count: {count}</text>
}

Common Patterns

List with Selection

function SelectList({ items }: { items: string[] }) {
  const [selectedIndex, setSelectedIndex] = useState(0)

  useKeyboard((key) => {
    if (key.name === "down" || (key.name === "tab" && !key.shift)) {
      setSelectedIndex(i => Math.min(i + 1, items.length - 1))
    }
    if (key.name === "up" || (key.name === "tab" && key.shift)) {
      setSelectedIndex(i => Math.max(i - 1, 0))
    }
    if (key.name === "enter") {
      console.log("Selected:", items[selectedIndex])
    }
  })

  return (
    <scrollbox height={20}>
      {items.map((item, index) => (
        <box
          key={index}
          backgroundColor={
            index === selectedIndex
              ? { r: 100, g: 149, b: 237 }
              : { r: 30, g: 30, b: 30 }
          }
        >
          <text
            foregroundColor={
              index === selectedIndex
                ? { r: 255, g: 255, b: 255 }
                : { r: 255, g: 255, b: 255 }
            }
          >
            {index === selectedIndex ? "> " : "  "}{item}
          </text>
        </box>
      ))}
    </scrollbox>
  )
}

Tabs

function Tabs({ tabs }: { tabs: Array<{ id: string, label: string, content: any }> }) {
  const [activeTab, setActiveTab] = useState(tabs[0].id)

  return (
    <box flexDirection="column" height={30}>
      {/* Tab headers */}
      <box flexDirection="row">
        {tabs.map(tab => (
          <box
            key={tab.id}
            onClick={() => setActiveTab(tab.id)}
            borderStyle={activeTab === tab.id ? "single" : "none"}
            backgroundColor={
              activeTab === tab.id
                ? { r: 100, g: 149, b: 237 }
                : { r: 50, g: 50, b: 50 }
            }
            padding={1}
          >
            <text>{tab.label}</text>
          </box>
        ))}
      </box>

      {/* Tab content */}
      <box flexGrow={1} padding={1}>
        {tabs.find(t => t.id === activeTab)?.content}
      </box>
    </box>
  )
}

Modal/Dialog

function Modal({ isOpen, onClose, children }: any) {
  if (!isOpen) return null

  return (
    <box
      position="absolute"
      top={0}
      left={0}
      width="100%"
      height="100%"
      backgroundColor={{ r: 0, g: 0, b: 0, a: 0.5 }}
      justifyContent="center"
      alignItems="center"
      onClick={onClose}
    >
      <box
        borderStyle="double"
        backgroundColor={{ r: 30, g: 30, b: 30 }}
        padding={2}
        onClick={(e: any) => e.stopPropagation()}
      >
        {children}
      </box>
    </box>
  )
}

When to Use This Skill

Use /opentui-react for:

• Building TUIs with React
• Using hooks (useKeyboard, useRenderer, etc.)
• JSX-style component development
• Integrating with React state management
• Testing React OpenTUI components

For vanilla TypeScript/JavaScript, use /opentui For SolidJS development, use /opentui-solid For project scaffolding, use /opentui-projects

Resources

• Hooks Reference - Complete hook documentation
• Component Props - React component props
• Patterns - Common React patterns
• State Management - React state integration
• Testing - Testing React components

Key Knowledge Sources

• OpenTUI React GitHub: https://github.com/sst/opentui/tree/main/packages/react
• Context7: /sst/opentui - React integration queries
• Research: .search-data/research/opentui/

OpenTUI React Hooks Reference

useKeyboard

Handle keyboard events at the component level.

import { useKeyboard, KeyEvent } from "@opentui/react"

function Component() {
  useKeyboard((key: KeyEvent) => {
    console.log(key.name, key.sequence, key.ctrl, key.shift, key.meta)
  })

  return <text>Listening for keyboard events</text>
}

Key Properties:

• name: string - Key name ('a', 'enter', 'escape', etc.)
• sequence: string - Raw character sequence
• ctrl: boolean - Ctrl modifier
• shift: boolean - Shift modifier
• meta: boolean - Meta/Command modifier

Cleanup: Hook automatically cleans up on unmount.

---

useRenderer

Access the underlying CliRenderer instance.

import { useRenderer } from "@opentui/react"

function Component() {
  const renderer = useRenderer()

  const destroy = () => {
    renderer.destroy()
    process.exit(0)
  }

  return <box onClick={destroy}>Exit</box>
}

Returns: CliRenderer instance

Use Cases:

• Manual renderer control
• Advanced event handling
• Performance optimization

---

useTerminalDimensions

Subscribe to terminal size changes.

import { useTerminalDimensions } from "@opentui/react"

function Responsive() {
  const { width, height } = useTerminalDimensions()

  const layout = width > 80 ? "desktop" : "mobile"

  return (
    <box>
      <text>Layout: {layout}</text>
      <text>Size: {width}x{height}</text>
    </box>
  )
}

Returns: { width: number, height: number }

Note: Automatically re-renders on terminal resize.

---

useTimeline

Create and manage animations.

import { useTimeline } from "@opentui/react"
import { useRef } from "react"

function AnimatedComponent() {
  const boxRef = useRef<any>(null)

  const timeline = useTimeline({
    duration: 1000,
    easing: (t) => t,
    loop: false,
  })

  const animate = () => {
    if (boxRef.current) {
      timeline.to(boxRef.current, {
        backgroundColor: { r: 255, g: 0, b: 0 },
      })
      timeline.play()
    }
  }

  return (
    <box ref={boxRef} onClick={animate}>
      <text>Click to animate</text>
    </box>
  )
}

Options:

• duration: number - Animation duration in ms
• easing: (t: number) => number - Easing function
• loop: boolean - Loop animation
• autoplay: boolean - Start automatically

Returns: Timeline instance

Methods:

• play() - Start animation
• pause() - Pause animation
• stop() - Stop and reset
• to(target, props, options) - Add animation

---

Custom Hooks

useFocus

function useFocus() {
  const [focused, setFocused] = useState(false)
  const ref = useRef<any>(null)

  useEffect(() => {
    const component = ref.current
    if (!component) return

    const onFocus = () => setFocused(true)
    const onBlur = () => setFocused(false)

    component.on("focus", onFocus)
    component.on("blur", onBlur)

    return () => {
      component.off("focus", onFocus)
      component.off("blur", onBlur)
    }
  }, [])

  return { ref, focused }
}

// Usage
function Input() {
  const { ref, focused } = useFocus()

  return (
    <box
      ref={ref}
      borderStyle={focused ? "double" : "single"}
    >
      <input />
    </box>
  )
}

useInput

function useInput(initialValue: string = "") {
  const [value, setValue] = useState(initialValue)
  const ref = useRef<any>(null)

  useEffect(() => {
    const component = ref.current
    if (!component) return

    const onChange = (newValue: string) => setValue(newValue)
    const onSubmit = (submittedValue: string) => {
      console.log("Submitted:", submittedValue)
    }

    component.on("change", onChange)
    component.on("submit", onSubmit)

    return () => {
      component.off("change", onChange)
      component.off("submit", onSubmit)
    }
  }, [])

  return { ref, value, setValue }
}

// Usage
function NameInput() {
  const { ref, value, setValue } = useInput("")

  return <input ref={ref} value={value} onChange={setValue} />
}

useKeyPress

function useKeyPress(keyFilter: string | string[] | ((key: KeyEvent) => boolean)) {
  const [pressed, setPressed] = useState(false)

  useKeyboard((key) => {
    let match = false

    if (typeof keyFilter === "string") {
      match = key.name === keyFilter
    } else if (Array.isArray(keyFilter)) {
      match = keyFilter.includes(key.name)
    } else if (typeof keyFilter === "function") {
      match = keyFilter(key)
    }

    if (match) {
      setPressed(true)
      setTimeout(() => setPressed(false), 100)
    }
  })

  return pressed
}

// Usage
function SaveButton() {
  const isPressed = useKeyPress((key) => key.name === "s" && key.ctrl)

  return (
    <box
      borderStyle={isPressed ? "double" : "single"}
    >
      <text>{isPressed ? "Saving..." : "Save (Ctrl+S)"}</text>
    </box>
  )
}

useListNavigation

function useListNavigation(itemCount: number) {
  const [selectedIndex, setSelectedIndex] = useState(0)

  useKeyboard((key) => {
    if (key.name === "down" || (key.name === "tab" && !key.shift)) {
      setSelectedIndex(i => Math.min(i + 1, itemCount - 1))
    }
    if (key.name === "up" || (key.name === "tab" && key.shift)) {
      setSelectedIndex(i => Math.max(i - 1, 0))
    }
    if (key.name === "home") {
      setSelectedIndex(0)
    }
    if (key.name === "end") {
      setSelectedIndex(itemCount - 1)
    }
  })

  return { selectedIndex, setSelectedIndex }
}

// Usage
function List({ items }: { items: string[] }) {
  const { selectedIndex } = useListNavigation(items.length)

  return (
    <scrollbox>
      {items.map((item, index) => (
        <box
          key={index}
          backgroundColor={
            index === selectedIndex
              ? { r: 100, g: 149, b: 237 }
              : { r: 30, g: 30, b: 30 }
          }
        >
          <text>{item}</text>
        </box>
      ))}
    </scrollbox>
  )
}

useModal

function useModal() {
  const [isOpen, setIsOpen] = useState(false)

  const open = () => setIsOpen(true)
  const close = () => setIsOpen(false)
  const toggle = () => setIsOpen(!isOpen)

  useKeyboard((key) => {
    if (key.name === "escape" && isOpen) {
      close()
    }
  })

  return { isOpen, open, close, toggle }
}

// Usage
function App() {
  const modal = useModal()

  return (
    <>
      <box onClick={modal.open}>
        <text>Open Modal</text>
      </box>

      {modal.isOpen && (
        <Modal onClose={modal.close}>
          <text>Modal content</text>
        </Modal>
      )}
    </>
  )
}

Hook Patterns

Combining Hooks

function Component() {
  const { width, height } = useTerminalDimensions()
  const renderer = useRenderer()

  useKeyboard((key) => {
    if (key.name === "c" && key.ctrl) {
      renderer.destroy()
      process.exit(0)
    }
  })

  return (
    <box width={width} height={height}>
      <text>Press Ctrl+C to exit</text>
    </box>
  )
}

Hook Dependencies

function SearchableList({ items }: { items: string[] }) {
  const [query, setQuery] = useState("")
  const [selectedIndex, setSelectedIndex] = useState(0)

  const filteredItems = items.filter(item =>
    item.toLowerCase().includes(query.toLowerCase())
  )

  // Update selected index when filter changes
  useEffect(() => {
    setSelectedIndex(0)
  }, [query])

  useKeyboard((key) => {
    if (key.name === "down") {
      setSelectedIndex(i => Math.min(i + 1, filteredItems.length - 1))
    }
  })

  return (
    <box flexDirection="column">
      <input value={query} onChange={setQuery} placeholder="Search..." />
      <scrollbox>
        {filteredItems.map((item, index) => (
          <box
            key={index}
            backgroundColor={index === selectedIndex ? { r: 100, g: 149, b: 237 } : { r: 30, g: 30, b: 30 }}
          >
            <text>{item}</text>
          </box>
        ))}
      </scrollbox>
    </box>
  )
}

Reference

• React Hooks: https://react.dev/reference/react
• OpenTUI React Source: https://github.com/sst/opentui/tree/main/packages/react
• Examples: .search-data/research/opentui/resources.md

OpenTUI React Patterns

Form Patterns

Controlled Form

function ControlledForm() {
  const [formData, setFormData] = useState({
    name: "",
    email: "",
    message: "",
  })

  const handleChange = (field: string) => (value: string) => {
    setFormData(prev => ({ ...prev, [field]: value }))
  }

  const handleSubmit = () => {
    console.log("Form submitted:", formData)
  }

  useKeyboard((key) => {
    if (key.name === "enter" && key.ctrl) {
      handleSubmit()
    }
  })

  return (
    <box flexDirection="column" gap={1} padding={2}>
      <text decoration="bold">Contact Form</text>

      <input
        value={formData.name}
        onChange={handleChange("name")}
        placeholder="Name"
      />

      <input
        value={formData.email}
        onChange={handleChange("email")}
        placeholder="Email"
      />

      <textarea
        value={formData.message}
        onChange={handleChange("message")}
        placeholder="Message"
        rows={5}
      />

      <box onClick={handleSubmit} borderStyle="single" padding={1}>
        <text>Submit (Ctrl+Enter)</text>
      </box>
    </box>
  )
}

Form with Validation

function ValidatedForm() {
  const [formData, setFormData] = useState({
    email: "",
    password: "",
  })
  const [errors, setErrors] = useState<Record<string, string>>({})
  const [touched, setTouched] = useState<Record<string, boolean>>({})

  const validate = (field: string, value: string): string | null => {
    switch (field) {
      case "email":
        return !value.includes("@") ? "Invalid email" : null
      case "password":
        return value.length < 8 ? "Password too short" : null
      default:
        return null
    }
  }

  const handleChange = (field: string) => (value: string) => {
    setFormData(prev => ({ ...prev, [field]: value }))

    if (touched[field]) {
      const error = validate(field, value)
      setErrors(prev => ({ ...prev, [field]: error || "" }))
    }
  }

  const handleBlur = (field: string) => () => {
    setTouched(prev => ({ ...prev, [field]: true }))
    const error = validate(field, formData[field as keyof typeof formData])
    setErrors(prev => ({ ...prev, [field]: error || "" }))
  }

  const isValid = Object.values(errors).every(e => !e)

  return (
    <box flexDirection="column" gap={1}>
      <text decoration="bold">Register</text>

      <input
        value={formData.email}
        onChange={handleChange("email")}
        onBlur={handleBlur("email")}
        placeholder="Email"
      />
      {touched.email && errors.email && (
        <text foregroundColor={{ r: 231, g: 76, b: 60 }}>
          {errors.email}
        </text>
      )}

      <input
        value={formData.password}
        onChange={handleChange("password")}
        onBlur={handleBlur("password")}
        placeholder="Password"
        password
      />
      {touched.password && errors.password && (
        <text foregroundColor={{ r: 231, g: 76, b: 60 }}>
          {errors.password}
        </text>
      )}

      <box
        onClick={() => isValid && console.log("Submit", formData)}
        borderStyle={isValid ? "single" : "dashed"}
        opacity={isValid ? 1 : 0.5}
      >
        <text>Submit</text>
      </box>
    </box>
  )
}

Navigation Patterns

Menu

function Menu({ items, onSelect }: { items: string[], onSelect: (item: string) => void }) {
  const [selectedIndex, setSelectedIndex] = useState(0)

  useKeyboard((key) => {
    if (key.name === "down") {
      setSelectedIndex(i => Math.min(i + 1, items.length - 1))
    }
    if (key.name === "up") {
      setSelectedIndex(i => Math.max(i - 1, 0))
    }
    if (key.name === "enter") {
      onSelect(items[selectedIndex])
    }
  })

  return (
    <box borderStyle="single" padding={1}>
      {items.map((item, index) => (
        <box
          key={index}
          backgroundColor={
            index === selectedIndex
              ? { r: 100, g: 149, b: 237 }
              : undefined
          }
        >
          <text>
            {index === selectedIndex ? "> " : "  "}
            {item}
          </text>
        </box>
      ))}
    </box>
  )
}

Breadcrumbs

function Breadcrumbs({ items }: { items: Array<{ label: string, onClick: () => void }> }) {
  return (
    <box flexDirection="row" gap={1}>
      {items.map((item, index) => (
        <box key={index}>
          <text
            foregroundColor={{ r: 100, g: 149, b: 237 }}
            onClick={item.onClick}
          >
            {item.label}
          </text>
          {index < items.length - 1 && (
            <text> / </text>
          )}
        </box>
      ))}
    </box>
  )
}

Layout Patterns

App Shell

function AppShell({ sidebar, main, footer }: any) {
  const { width, height } = useTerminalDimensions()

  return (
    <box
      flexDirection="column"
      width={width}
      height={height}
    >
      {/* Header */}
      <box
        height={3}
        borderStyle="double"
        backgroundColor={{ r: 30, g: 30, b: 30 }}
      >
        <text decoration="bold">My App</text>
      </box>

      {/* Main content area */}
      <box flexDirection="row" flexGrow={1}>
        {/* Sidebar */}
        <box
          width={20}
          borderStyle="single"
          backgroundColor={{ r: 25, g: 25, b: 25 }}
        >
          {sidebar}
        </box>

        {/* Main content */}
        <box flexGrow={1} padding={1}>
          {main}
        </box>
      </box>

      {/* Footer */}
      <box
        height={2}
        borderStyle="single"
        backgroundColor={{ r: 30, g: 30, b: 30 }}
      >
        {footer}
      </box>
    </box>
  )
}

Split Pane

function SplitPane({
  left,
  right,
  splitPosition = 0.5,
  onSplitChange,
}: any) {
  const [isDragging, setIsDragging] = useState(false)

  useKeyboard((key) => {
    if (!isDragging) return

    const delta = key.name === "left" ? -1 : key.name === "right" ? 1 : 0
    if (delta !== 0) {
      onSplitChange(Math.max(0.1, Math.min(0.9, splitPosition + delta * 0.01)))
    }
  })

  const leftWidth = Math.floor(80 * splitPosition)
  const rightWidth = 80 - leftWidth

  return (
    <box flexDirection="row" width={80}>
      <box width={leftWidth}>
        {left}
      </box>

      {/* Resizer */}
      <box
        width={1}
        backgroundColor={{ r: 100, g: 149, b: 237 }}
        onClick={() => setIsDragging(!isDragging)}
      >
        <text>{isDragging ? "||" : "|"}</text>
      </box>

      <box width={rightWidth}>
        {right}
      </box>
    </box>
  )
}

Data Display Patterns

Table

function Table({ columns, rows }: {
  columns: Array<{ key: string, label: string }>
  rows: Record<string, any>[]
}) {
  const [selectedIndex, setSelectedIndex] = useState(0)
  const [scrollOffset, setScrollOffset] = useState(0)

  useKeyboard((key) => {
    if (key.name === "down") {
      setSelectedIndex(i => Math.min(i + 1, rows.length - 1))
    }
    if (key.name === "up") {
      setSelectedIndex(i => Math.max(i - 1, 0))
    }
  })

  const columnWidths = columns.map(() =>
    Math.floor(80 / columns.length)
  )

  return (
    <box flexDirection="column">
      {/* Header */}
      <box flexDirection="row" borderStyle="single">
        {columns.map((col, index) => (
          <box
            key={col.key}
            width={columnWidths[index]}
            borderStyle="single"
          >
            <text decoration="bold">{col.label}</text>
          </box>
        ))}
      </box>

      {/* Rows */}
      <scrollbox height={20}>
        {rows.map((row, rowIndex) => (
          <box
            key={rowIndex}
            flexDirection="row"
            backgroundColor={
              rowIndex === selectedIndex
                ? { r: 100, g: 149, b: 237 }
                : undefined
            }
          >
            {columns.map((col, colIndex) => (
              <box
                key={col.key}
                width={columnWidths[colIndex]}
                borderStyle="single"
              >
                <text>{String(row[col.key])}</text>
              </box>
            ))}
          </box>
        ))}
      </scrollbox>
    </box>
  )
}

Card List

function CardList({ items }: { items: Array<{ title: string, description: string }> }) {
  return (
    <scrollbox height={25}>
      {items.map((item, index) => (
        <box
          key={index}
          borderStyle="single"
          marginBottom={1}
          padding={1}
        >
          <text decoration="bold">{item.title}</text>
          <text>{item.description}</text>
        </box>
      ))}
    </scrollbox>
  )
}

Interactive Patterns

Confirm Dialog

function ConfirmDialog({
  message,
  onConfirm,
  onCancel,
}: {
  message: string
  onConfirm: () => void
  onCancel: () => void
}) {
  const [selected, setSelected] = useState<"confirm" | "cancel">("confirm")

  useKeyboard((key) => {
    if (key.name === "left") setSelected("confirm")
    if (key.name === "right") setSelected("cancel")
    if (key.name === "enter") {
      if (selected === "confirm") onConfirm()
      else onCancel()
    }
    if (key.name === "escape") onCancel()
  })

  return (
    <box
      position="absolute"
      top={5}
      left={20}
      width={40}
      height={10}
      borderStyle="double"
      backgroundColor={{ r: 30, g: 30, b: 30 }}
      flexDirection="column"
      padding={2}
    >
      <text marginBottom={1}>{message}</text>

      <box flexDirection="row" gap={2}>
        <box
          borderStyle={selected === "confirm" ? "double" : "single"}
          padding={1}
        >
          <text>OK</text>
        </box>
        <box
          borderStyle={selected === "cancel" ? "double" : "single"}
          padding={1}
        >
          <text>Cancel</text>
        </box>
      </box>
    </box>
  )
}

Progress Bar

function ProgressBar({ progress, total }: { progress: number, total: number }) {
  const percentage = Math.floor((progress / total) * 100)
  const barWidth = 40
  const filledWidth = Math.floor((progress / total) * barWidth)

  return (
    <box>
      <text>{percentage}% </text>
      <text>[</text>
      <text
        backgroundColor={{ r: 46, g: 204, b: 113 }}
      >
        {"=".repeat(filledWidth)}
      </text>
      <text>{" ".repeat(barWidth - filledWidth)}]</text>
    </box>
  )
}

Loading Spinner

function LoadingSpinner({ message = "Loading..." }: { message?: string }) {
  const [frame, setFrame] = useState(0)

  useEffect(() => {
    const interval = setInterval(() => {
      setFrame(f => (f + 1) % 4)
    }, 250)

    return () => clearInterval(interval)
  }, [])

  const spinners = ["|", "/", "-", "\\"]

  return (
    <box>
      <text>{spinners[frame]} {message}</text>
    </box>
  )
}

Reference

• React Patterns: https://react.dev/learn
• OpenTUI Examples: .search-data/research/opentui/resources.md

OpenTUI React Component Props

Common Props

All OpenTUI React components share these common props:

Layout Props

<box
  flexDirection="row"
  justifyContent="center"
  alignItems="center"
  gap={1}
  width={80}
  height={20}
  flexGrow={1}
  flexShrink={0}
/>

Props:

• flexDirection: "row" | "column" | "row-reverse" | "column-reverse"
• justifyContent: "flex-start" | "center" | "flex-end" | "space-between" | "space-around" | "space-evenly"
• alignItems: "flex-start" | "center" | "flex-end" | "stretch"
• alignContent: "flex-start" | "center" | "flex-end" | "stretch" | "space-between" | "space-around"
• flexWrap: "nowrap" | "wrap" | "wrap-reverse"
• gap?: number
• rowGap?: number
• columnGap?: number
• flexGrow?: number
• flexShrink?: number
• flexBasis?: number | "auto"
• alignSelf?: "auto" | "flex-start" | "center" | "flex-end" | "stretch"
• width?: number | "auto"
• height?: number | "auto"
• minWidth?: number
• minHeight?: number
• maxWidth?: number
• maxHeight?: number
• position?: "relative" | "absolute"
• top?: number
• left?: number
• right?: number
• bottom?: number

Style Props

<box
  backgroundColor={{ r: 30, g: 30, b: 30 }}
  foregroundColor={{ r: 255, g: 255, b: 255 }}
  borderStyle="single"
  borderColor={{ r: 100, g: 149, b: 237 }}
  padding={1}
  paddingTop={1}
  paddingBottom={1}
  paddingLeft={2}
  paddingRight={2}
/>

Props:

• backgroundColor?: { r: number, g: number, b: number, a?: number }
• foregroundColor?: { r: number, g: number, b: number, a?: number }
• borderStyle?: "single" | "double" | "round" | "bold" | "dashed" | "none"
• borderColor?: { r: number, g: number, b: number, a?: number }
• padding?: number
• paddingTop?: number
• paddingBottom?: number
• paddingLeft?: number
• paddingRight?: number

Event Props

<box
  onClick={(event) => console.log("Clicked!", event)}
  onMouseover={(event) => console.log("Hovered!", event)}
  onMouseout={(event) => console.log("Left!", event)}
/>

Props:

• onClick?: (event: MouseEvent) => void
• onMouseover?: (event: MouseEvent) => void
• onMouseout?: (event: MouseEvent) => void

Component-Specific Props

<text>

<text
  value="Hello, World!"
  decoration="bold underline"
/>

Props:

• value?: string - Text content (can also use children)
• decoration?: "bold" | "dim" | "italic" | "underline" | "blink" | "inverse" | "hidden" | "strikethrough"
• wrap?: boolean - Enable text wrapping

<box>

<box
  borderStyle="single"
  backgroundColor={{ r: 30, g: 30, b: 30 }}
  padding={1}
>
  <text>Content</text>
</box>

All common props apply.

<input>

<input
  value={text}
  onChange={setText}
  placeholder="Enter text..."
  password={false}
  placeholderColor={{ r: 128, g: 128, b: 128 }}
  cursorColor={{ r: 255, g: 255, b: 255 }}
/>

Props:

• value?: string - Input value
• onChange?: (value: string) => void - Value change handler
• onSubmit?: (value: string) => void - Submit (Enter) handler
• onFocus?: () => void - Focus handler
• onBlur?: () => void - Blur handler
• placeholder?: string - Placeholder text
• password?: boolean - Password mode (hide input)
• placeholderColor?: { r: number, g: number, b: number, a?: number }
• cursorColor?: { r: number, g: number, b: number, a?: number }

<select>

<select
  value={selectedValue}
  onChange={setSelectedValue}
  options={[
    { label: "Option 1", value: "1" },
    { label: "Option 2", value: "2" },
  ]}
/>

Props:

• value?: string - Selected value
• onChange?: (value: string) => void - Selection change handler
• onSubmit?: (value: string) => void - Submit handler
• options?: Array<{ label: string, value: string }> - Available options
• onFocus?: () => void - Focus handler
• onBlur?: () => void - Blur handler

<scrollbox>

<scrollbox
  width={60}
  height={20}
  onScroll={(offset) => console.log("Scrolled to", offset)}
>
  <text>Item 1</text>
  <text>Item 2</text>
  {/* ... more items ... */}
</scrollbox>

Props:

• width?: number - Width
• height?: number - Height
• onScroll?: (offset: number) => void - Scroll handler
• All common style props apply

<code>

<code
  code={`function hello() {\n  console.log("Hello!");\n}`}
  language="javascript"
/>

Props:

• code?: string - Code to display (can also use children)
• language?: string - Syntax highlighting language
• javascript, typescript
• python, rust, go
• json, yaml, xml
• html, css
• bash, shell
• And more...

<textarea>

<textarea
  value={longText}
  onChange={setLongText}
  rows={5}
  cols={60}
/>

Props:

• value?: string - Text content
• onChange?: (value: string) => void - Change handler
• onSubmit?: (value: string) => void - Submit handler
• rows?: number - Height in rows
• cols?: number - Width in columns
• placeholder?: string - Placeholder text
• onFocus?: () => void - Focus handler
• onBlur?: () => void - Blur handler

Color Format

Colors in React are objects:

// RGB
{ r: 255, g: 0, b: 0 }

// RGBA
{ r: 255, g: 0, b: 0, a: 0.5 }

Ranges:

• r, g, b: 0-255
• a: 0.0-1.0

Ref Props

All components support refs:

import { useRef } from "react"

function Component() {
  const boxRef = useRef<any>(null)

  const handleClick = () => {
    console.log(boxRef.current)
  }

  return <box ref={boxRef} onClick={handleClick}>Content</box>
}

Children

Components accept children as JSX:

<box flexDirection="column">
  <text>Title</text>
  <input />
  <text>Footer</text>
</box>

Or as arrays:

<box>
  {items.map((item, index) => (
    <text key={index}>{item}</text>
  ))}
</box>

TypeScript Types

import type { Color } from "@opentui/react"

interface MyComponentProps {
  backgroundColor?: Color
  borderStyle?: "single" | "double" | "round" | "bold" | "dashed" | "none"
  onClick?: (event: MouseEvent) => void
}

Reference

• Component Source: https://github.com/sst/opentui/tree/main/packages/react
• Examples: .search-data/research/opentui/resources.md

OpenTUI React State Management

Local State (useState)

For component-local state, use React's built-in useState:

import { useState } from "react"

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

  useKeyboard((key) => {
    if (key.name === "up") setCount(c => c + 1)
    if (key.name === "down") setCount(c => c - 1)
  })

  return <text>Count: {count}</text>
}

Context API

For sharing state across components:

import { createContext, useContext, useState } from "react"

// Create context
const AppContext = createContext<any>(null)

// Provider component
function AppProvider({ children }: { children: any }) {
  const [theme, setTheme] = useState("dark")
  const [user, setUser] = useState(null)

  return (
    <AppContext.Provider value={{ theme, setTheme, user, setUser }}>
      {children}
    </AppContext.Provider>
  )
}

// Custom hook to use context
function useAppContext() {
  const context = useContext(AppContext)
  if (!context) {
    throw new Error("useAppContext must be used within AppProvider")
  }
  return context
}

// Usage in components
function ThemedComponent() {
  const { theme, setTheme } = useAppContext()

  return (
    <box
      backgroundColor={theme === "dark" ? { r: 30, g: 30, b: 30 } : { r: 255, g: 255, b: 255 }}
    >
      <text>Current theme: {theme}</text>
    </box>
  )
}

Redux Integration

Setup

bun install @reduxjs/toolkit react-redux

Configure Store

import { configureStore, createSlice } from "@reduxjs/toolkit"

// Create slice
const counterSlice = createSlice({
  name: "counter",
  initialState: { value: 0 },
  reducers: {
    increment: (state) => {
      state.value += 1
    },
    decrement: (state) => {
      state.value -= 1
    },
    incrementByAmount: (state, action) => {
      state.value += action.payload
    },
  },
})

export const { increment, decrement, incrementByAmount } = counterSlice.actions
export const counterReducer = counterSlice.reducer

// Configure store
export const store = configureStore({
  reducer: {
    counter: counterReducer,
  },
})

// Type definitions
type RootState = ReturnType<typeof store.getState>
type AppDispatch = typeof store.dispatch

Provider Setup

import { Provider } from "react-redux"
import { store } from "./store"

function App() {
  return (
    <Provider store={store}>
      <Counter />
    </Provider>
  )
}

Using Redux in Components

import { useSelector, useDispatch } from "react-redux"
import { increment, decrement, incrementByAmount } from "./store"

function Counter() {
  const count = useSelector((state: RootState) => state.counter.value)
  const dispatch = useDispatch()

  useKeyboard((key) => {
    if (key.name === "up") dispatch(increment())
    if (key.name === "down") dispatch(decrement())
    if (key.name === "right") dispatch(incrementByAmount(10))
  })

  return (
    <box>
      <text>Count: {count}</text>
      <text>Arrow keys to change</text>
    </box>
  )
}

Zustand Integration

Setup

bun install zustand

Create Store

import { create } from "zustand"

interface CounterState {
  count: number
  increment: () => void
  decrement: () => void
  incrementByAmount: (amount: number) => void
}

const useCounterStore = create<CounterState>((set) => ({
  count: 0,
  increment: () => set((state) => ({ count: state.count + 1 })),
  decrement: () => set((state) => ({ count: state.count - 1 })),
  incrementByAmount: (amount) => set((state) => ({ count: state.count + amount })),
}))

Use Store in Components

function Counter() {
  const { count, increment, decrement, incrementByAmount } = useCounterStore()

  useKeyboard((key) => {
    if (key.name === "up") increment()
    if (key.name === "down") decrement()
    if (key.name === "right") incrementByAmount(10)
  })

  return (
    <box>
      <text>Count: {count}</text>
    </box>
  )
}

With DevTools

import { create } from "zustand"
import { devtools } from "zustand/middleware"

const useCounterStore = create<CounterState>()(
  devtools((set) => ({
    count: 0,
    increment: () => set((state) => ({ count: state.count + 1 })),
    decrement: () => set((state) => ({ count: state.count - 1 })),
  }))
)

Jotai Integration

Setup

bun install jotai

Create Atoms

import { atom, useAtom } from "jotai"

// Primitive atom
const countAtom = atom(0)

// Read-only derived atom
const doubleCountAtom = atom((get) => get(countAtom) * 2)

// Read-write derived atom
const countWithStepsAtom = atom(
  (get) => get(countAtom),
  (get, set, newValue: number) => {
    set(countAtom, Math.floor(newValue / 10) * 10)
  }
)

Use Atoms in Components

function Counter() {
  const [count, setCount] = useAtom(countAtom)
  const [doubleCount] = useAtom(doubleCountAtom)

  useKeyboard((key) => {
    if (key.name === "up") setCount(c => c + 1)
    if (key.name === "down") setCount(c => c - 1)
  })

  return (
    <box>
      <text>Count: {count}</text>
      <text>Double: {doubleCount}</text>
    </box>
  )
}

React Query Integration

Setup

bun install @tanstack/react-query

Configure Query Client

import { QueryClient, QueryClientProvider } from "@tanstack/react-query"

const queryClient = new QueryClient()

function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <DataList />
    </QueryClientProvider>
  )
}

Fetch Data

import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query"

async function fetchItems() {
  const response = await fetch("https://api.example.com/items")
  return response.json()
}

function DataList() {
  const { data, isLoading, error } = useQuery({
    queryKey: ["items"],
    queryFn: fetchItems,
  })

  if (isLoading) return <text>Loading...</text>
  if (error) return <text>Error: {error.message}</text>

  return (
    <scrollbox>
      {data.map((item: any) => (
        <text key={item.id}>{item.name}</text>
      ))}
    </scrollbox>
  )
}

Focus Management State

Managing Focus Across Components

// Focus context
const FocusContext = createContext<any>(null)

function FocusProvider({ children }: { children: any }) {
  const [focusedComponent, setFocusedComponent] = useState<string | null>(null)

  const register = (id: string) => {
    if (!focusedComponent) {
      setFocusedComponent(id)
    }
  }

  const focus = (id: string) => {
    setFocusedComponent(id)
  }

  return (
    <FocusContext.Provider value={{ focusedComponent, register, focus }}>
      {children}
    </FocusContext.Provider>
  )
}

// Focusable component
function FocusableBox({ id, children }: any) {
  const { focusedComponent, register, focus } = useContext(FocusContext)

  useEffect(() => {
    register(id)
  }, [id, register])

  const isFocused = focusedComponent === id

  useKeyboard((key) => {
    if (!isFocused) return
    // Handle keyboard when focused
  })

  return (
    <box
      borderStyle={isFocused ? "double" : "single"}
      onClick={() => focus(id)}
    >
      {children}
    </box>
  )
}

Form State Management

React Hook Form Integration

bun install react-hook-form

import { useForm } from "react-hook-form"

function MyForm() {
  const { register, handleSubmit, formState: { errors } } = useForm({
    defaultValues: {
      name: "",
      email: "",
    },
  })

  const onSubmit = (data: any) => {
    console.log(data)
  }

  return (
    <box flexDirection="column" gap={1}>
      <input
        {...register("name", { required: "Name is required" })}
        placeholder="Name"
      />
      {errors.name && (
        <text foregroundColor={{ r: 231, g: 76, b: 60 }}>
          {errors.name.message}
        </text>
      )}

      <input
        {...register("email", { required: "Email is required" })}
        placeholder="Email"
      />
      {errors.email && (
        <text foregroundColor={{ r: 231, g: 76, b: 60 }}>
          {errors.email.message}
        </text>
      )}

      <box onClick={handleSubmit(onSubmit)}>
        <text>Submit</text>
      </box>
    </box>
  )
}

Async State Patterns

Async Actions with useState

function AsyncComponent() {
  const [data, setData] = useState(null)
  const [loading, setLoading] = useState(false)
  const [error, setError] = useState(null)

  const fetchData = async () => {
    setLoading(true)
    setError(null)

    try {
      const response = await fetch("https://api.example.com/data")
      const json = await response.json()
      setData(json)
    } catch (err) {
      setError(err.message)
    } finally {
      setLoading(false)
    }
  }

  useKeyboard((key) => {
    if (key.name === "r" && key.ctrl) {
      fetchData()
    }
  })

  if (loading) return <text>Loading...</text>
  if (error) return <text>Error: {error}</text>

  return (
    <box>
      <text>Data: {JSON.stringify(data)}</text>
      <text>Press Ctrl+R to refresh</text>
    </box>
  )
}

Reference

• Redux Toolkit: https://redux-toolkit.js.org/
• Zustand: https://zustand-demo.pmnd.rs/
• Jotai: https://jotai.org/
• React Query: https://tanstack.com/query/latest

Testing OpenTUI React Components

Testing Setup

bun install @testing-library/react @testing-library/user-event vitest

Basic Component Test

import { render, screen } from "@testing-library/react"
import { createTestRenderer } from "@opentui/core/testing"
import { createRoot } from "@opentui/react"

describe("MyComponent", () => {
  it("should render text", async () => {
    const renderer = await createTestRenderer()
    const root = createRoot(renderer)

    render(
      root,
      <text>Hello, World!</text>
    )

    renderer.render()

    const output = renderer.getOutput()
    expect(output).toContain("Hello, World!")
  })
})

Testing Hooks

useKeyboard Hook

import { renderHook, act } from "@testing-library/react"
import { useKeyboard } from "@opentui/react"

describe("useKeyboard", () => {
  it("should call callback on key press", () => {
    const callback = vi.fn()

    renderHook(() => {
      useKeyboard(callback)
    })

    act(() => {
      // Simulate key event
      callback({ name: "enter", sequence: "\r", ctrl: false, shift: false, meta: false })
    })

    expect(callback).toHaveBeenCalled()
  })
})

Custom Hook Test

function useKeyPress(targetKey: string) {
  const [pressed, setPressed] = useState(false)

  useKeyboard((key) => {
    if (key.name === targetKey) {
      setPressed(true)
      setTimeout(() => setPressed(false), 100)
    }
  })

  return pressed
}

describe("useKeyPress", () => {
  it("should detect key press", () => {
    const { result } = renderHook(() => useKeyPress("enter"))

    expect(result.current).toBe(false)

    act(() => {
      // Trigger enter key
    })

    expect(result.current).toBe(true)
  })
})

Testing User Interactions

Keyboard Input

describe("InputComponent", () => {
  it("should update value on input", async () => {
    const renderer = await createTestRenderer()
    const root = createRoot(renderer)

    let value = ""

    render(
      root,
      <input
        value={value}
        onChange={(v) => value = v}
      />
    )

    // Simulate typing
    act(() => {
      // Simulate key events for "hello"
    })

    expect(value).toBe("hello")
  })
})

Click Events

describe("ButtonComponent", () => {
  it("should call onClick when clicked", async () => {
    const handleClick = vi.fn()
    const renderer = await createTestRenderer()
    const root = createRoot(renderer)

    render(
      root,
      <box onClick={handleClick}>
        <text>Click me</text>
      </box>
    )

    // Simulate mouse click
    renderer.simulateMouse({
      x: 5,
      y: 0,
      button: "left",
      action: "click",
      shift: false,
      ctrl: false,
      meta: false,
    })

    expect(handleClick).toHaveBeenCalled()
  })
})

Testing State Changes

useState Updates

describe("Counter", () => {
  it("should increment count", async () => {
    const renderer = await createTestRenderer()
    const root = createRoot(renderer)

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

      useKeyboard((key) => {
        if (key.name === "up") {
          setCount(c => c + 1)
        }
      })

      return <text>Count: {count}</text>
    }

    render(root, <Counter />)

    renderer.render()

    // Simulate up arrow key
    renderer.simulateKey({
      name: "up",
      sequence: "\u001B[A",
      ctrl: false,
      shift: false,
      meta: false,
    })

    renderer.render()

    const output = renderer.getOutput()
    expect(output).toContain("Count: 1")
  })
})

Testing Forms

describe("LoginForm", () => {
  it("should submit with valid data", async () => {
    const handleSubmit = vi.fn()
    const renderer = await createTestRenderer()
    const root = createRoot(renderer)

    render(
      root,
      <LoginForm onSubmit={handleSubmit} />
    )

    // Fill email
    // Fill password
    // Submit

    expect(handleClick).toHaveBeenCalledWith({
      email: "test@example.com",
      password: "password123",
    })
  })

  it("should show validation errors", async () => {
    const renderer = await createTestRenderer()
    const root = createRoot(renderer)

    render(
      root,
      <LoginForm />
    )

    // Submit empty form

    const output = renderer.getOutput()
    expect(output).toContain("Email is required")
    expect(output).toContain("Password is required")
  })
})

Testing Component Lifecycle

Mount and Unmount

describe("LifecycleComponent", () => {
  it("should setup on mount and cleanup on unmount", () => {
    const onMount = vi.fn()
    const onUnmount = vi.fn()

    function LifecycleComponent() {
      useEffect(() => {
        onMount()
        return onUnmount
      }, [])

      return <text>Test</text>
    }

    const { unmount } = render(<LifecycleComponent />)

    expect(onMount).toHaveBeenCalled()

    unmount()

    expect(onUnmount).toHaveBeenCalled()
  })
})

Testing Async Operations

Data Fetching

describe("DataComponent", () => {
  it("should show loading state", async () => {
    const renderer = await createTestRenderer()
    const root = createRoot(renderer)

    render(
      root,
      <DataComponent />
    )

    renderer.render()

    let output = renderer.getOutput()
    expect(output).toContain("Loading...")

    // Wait for async
    await new Promise(resolve => setTimeout(resolve, 1000))

    renderer.render()

    output = renderer.getOutput()
    expect(output).not.toContain("Loading...")
  })
})

Testing with Context

describe("ComponentWithContext", () => {
  it("should use context value", () => {
    const TestContext = createContext({ theme: "dark" })

    function ThemedComponent() {
      const { theme } = useContext(TestContext)
      return <text>Theme: {theme}</text>
    }

    const { getByText } = render(
      <TestContext.Provider value={{ theme: "light" }}>
        <ThemedComponent />
      </TestContext.Provider>
    )

    expect(getByText("Theme: light")).toBeInTheDocument()
  })
})

Integration Testing

Full User Flow

describe("User Registration Flow", () => {
  it("should complete registration", async () => {
    const renderer = await createTestRenderer()
    const root = createRoot(renderer)

    render(
      root,
      <App />
    )

    // Navigate to registration
    renderer.simulateKey({ name: "r", sequence: "r", ctrl: false, shift: false, meta: false })

    // Fill form
    // Validate fields
    // Submit

    // Verify success message
    const output = renderer.getOutput()
    expect(output).toContain("Registration successful!")
  })
})

Test Utilities

Create Test Wrapper

function createTestWrapper({ store }: { store?: any } = {}) {
  return ({ children }: { children: any }) => (
    <QueryClientProvider client={queryClient}>
      {store ? (
        <Provider store={store}>
          {children}
        </Provider>
      ) : children}
    </QueryClientProvider>
  )
}

// Usage
render(
  <MyComponent />,
  { wrapper: createTestWrapper({ store }) }
)

Mock Renderer

import { createTestRenderer } from "@opentui/core/testing"

export async function setupTest() {
  const renderer = await createTestRenderer()
  const root = createRoot(renderer)

  return { renderer, root }
}

// Usage
describe("MyTest", () => {
  it("should work", async () => {
    const { renderer, root } = await setupTest()

    render(root, <MyComponent />)

    // Test...
  })
})

Testing Best Practices

1. Test user behavior, not implementation

• Test what users see and interact with
• Don't test internal state or methods

2. Keep tests simple and focused

• One assertion per test when possible
• Clear test names that describe behavior

3. Mock external dependencies

• API calls, file system, timers
• Use vi.fn() for mocks

4. Use test-specific props

• Pass default props to simplify setup
• Override only what's needed for the test

5. Test edge cases

• Empty states
• Error conditions
• Boundary values

Reference

• Testing Library: https://testing-library.com/react
• Vitest: https://vitest.dev/
• OpenTUI Testing: @opentui/core/testing