Rendering

Gridland is JSX that renders to a cell grid, not HTML. The same component tree can run in three places:

• In a browser, drawn to an HTML5 <canvas> by @gridland/web
• In a terminal, drawn to real stdout by @gridland/bun over a native FFI bridge
• As plain text, rendered headlessly for AI agents, crawlers, screen readers, and server-side snapshots

All three paths accept the same components and hooks, so a single app can ship as an embedded web TUI, a standalone CLI binary, and an agent-readable document from one codebase. This page covers all three targets. Pick the section that matches where you want your UI to run.

In the browser

The @gridland/web package renders your TUI to an HTML <canvas> inside any React app Next.js, Vite, Remix, plain CRA. The TUI component is the single entry point: it handles client detection, canvas creation, reconciler setup, and automatic resizing. Gridland is built on the opentui engine.

 ╭───────────────────────────────────Layout───────────────────────────────────╮
 │                                                                            │
 │ ┌─────────────────────┐  ┌──────────────────────┐  ┌─────────────────────┐ │
 │ │                     │  │                      │  │                     │ │
 │ │ Box 1               │  │ Box 2                │  │ Box 3               │ │
 │ │                     │  │                      │  │                     │ │
 │ └─────────────────────┘  └──────────────────────┘  └─────────────────────┘ │
 │                                                                            │
 ╰────────────────────────────────────────────────────────────────────────────╯
   Nested boxes with borders, colors & flexbox layout

Run demo

bunx @gridland/demo primitives

curl -fsSL https://raw.githubusercontent.com/thoughtfulllc/gridland/main/scripts/run-demo.sh | bash -s primitives

Install

bun add @gridland/web

Usage

import { TUI } from "@gridland/web"

<TUI style={{ width: "100vw", height: "100vh" }}>
  <box border padding={1}>
    <text>Your TUI content here</text>
  </box>
</TUI>

SSR behavior

The client-side hydration process:

1. Detects the browser environment via useEffect
2. Creates a <canvas> element inside the container
3. Initializes the React reconciler with a BrowserRenderContext
4. Sets up ResizeObserver for automatic canvas resizing
5. Renders children through the TUI reconciler to the canvas

Architecture

React JSX
  |
  v
@opentui/react reconciler
  |
  v
Renderable tree (Box, Text, etc.)
  |
  v
Yoga layout engine (flexbox)
  |
  v
BrowserBuffer (cell grid)
  |
  v
CanvasPainter (pixels)
  |
  v
HTML5 Canvas

TUI props

In the terminal

The @gridland/bun package renders your React TUI to an actual terminal using Bun's FFI bridge to the OpenTUI native engine. Same components, same hooks, same JSX the output goes to stdout instead of a canvas.

Requirements

• Bun 1.0 or later the runtime uses bun:ffi, which only exists in Bun
• macOS (x64, arm64) or Linux (x64, arm64)
• Windows is not supported

Install

bun add @gridland/bun

Platform-specific native binaries ship as optional dependencies, so only the binary for your OS/arch is downloaded.

Usage

import { createCliRenderer, createRoot } from "@gridland/bun"

function App() {
  return (
    <box border padding={1}>
      <text>Hello from the terminal</text>
    </box>
  )
}

const renderer = await createCliRenderer({ exitOnCtrlC: true })
createRoot(renderer).render(<App />)

bun src/app.tsx

Compile to a standalone binary

Bun can compile your app to a self-contained executable no runtime required, users don't need Bun, Node, or npm installed:

bun build --compile src/app.tsx --outfile my-app
./my-app

createCliRenderer options

As plain text

Gridland components render to a canvas in a browser and to stdout in a terminal both are pixel/cell-based outputs that AI agents, crawlers, and screen readers can't read. Headless rendering solves this by rendering the same component tree to plain text instead. No canvas, no browser, no terminal just a string you can hand to an LLM or embed in an HTML page for search indexing.

This is a first-class render target, not a workaround. The same component tree produces different output depending on who's looking at it:

• A human in a browser sees the canvas-drawn TUI
• A human in a terminal sees the stdout-drawn TUI
• An agent, crawler, or screen reader sees the plain-text version

No separate accessibility layer, no server-side rewrite, no duplicated markup. Concretely, this means an AI agent browsing your site can read a Gridland chat interface, and a search engine can index the content of a Gridland component that's rendered to a canvas.

See the SSR for Agents guide for how to wire this into a Next.js app or any server-rendered React framework.

Which target should I pick?

All three runtimes accept the same component tree, so you can share code across a terminal build, a browser build, and an agent-readable build of the same app.