GPUIX

React bindings for GPUI - Zed's GPU-accelerated UI framework.

Build native GPU-accelerated desktop apps with React and TypeScript. Your components render directly to the GPU via Metal, DirectX, or Vulkan. No Electron, no web views.

Everything above is GPUIX: the sidebar, the scrolling list, the composer, and native <markdown>. Start it with bun --hot so a save remounts React on the same window:

cd examples && bun --hot chat.tsx

Quickstart

Create an app from the official example. The command downloads only example-app/ and installs its dependencies. There is no repository clone, native build, or Rust toolchain.

bunx @gpuix/cli new my-app
cd my-app
bun run dev

@gpuix/react pulls the native renderer for your platform. Edit app.tsx and the running window remounts on save.

Build from scratch

Install the packages directly when you do not want the example app:

bun add @gpuix/react react
bun add -d @types/react typescript

1. Point TypeScript at the GPUIX JSX types

jsxImportSource is required. Without it TypeScript uses DOM types, so <virtual-list>, <markdown>, <code> and style.hover all fail to typecheck.

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "jsx": "react-jsx",
    "jsxImportSource": "@gpuix/react",
    "strict": true,
    "skipLibCheck": true,
    "noEmit": true
  }
}

2. Write the entry file

End the file with render(). That call creates the window, mounts React, and starts the frame loop.

import { useState } from 'react'
import { render } from '@gpuix/react'

function App() {
  const [count, setCount] = useState(0)
  return (
    <div style={{ padding: 24, backgroundColor: '#1a1a1a', height: '100%' }}>
      <div
        onClick={() => setCount((c) => c + 1)}
        style={{
          padding: 12,
          borderRadius: 8,
          cursor: 'pointer',
          backgroundColor: '#232323',
          hover: { backgroundColor: '#2c2c2c' },
        }}
      >
        <text style={{ color: '#e2e2e2' }}>Count: {count}</text>
      </div>
    </div>
  )
}

render(<App />, { title: 'My App', width: 800, height: 600 })

3. Run it

bun --hot app.tsx

Use bun --hot, not plain bun. A save then remounts React on the same window instead of opening a second one.

4. Ship a binary

bun build --compile app.tsx --outfile dist/app
./dist/app

The binary carries the renderer, so it runs with no Bun and no Node install.

Start from the example app

example-app/ is a complete todo app in one file, with dev, build, web:dev and typecheck scripts already wired. Create a copy with bunx @gpuix/cli new my-app.

Shell completions

Install completions for the gpuix command:

bun add -g @gpuix/cli
gpuix completions install

Examples

The todo app lives in example-app/ and is meant to be copied. The rest live in examples/. All of them use hardcoded data.

Or download a standalone chat build from the GitHub release. No Bun or Rust install is required.

tar -xzf example-chat-aarch64-apple-darwin.tar.gz
./example-chat-aarch64-apple-darwin

The archive keeps the executable bit, so there is no chmod step. macOS may still block the unsigned binary the first time. Right-click the file, choose Open, and confirm.

On Windows, download example-chat-x86_64-pc-windows-msvc.exe and double-click it. On Linux, the file is example-chat-x86_64-unknown-linux-gnu.tar.gz.

The web example bundles the same React app and reconciler as the desktop chat example. wasm-bindgen exposes the mutation interface to the existing retained tree and GpuixView, which run through GPUI's browser platform. Browser event callbacks are not supported yet.

The web build needs nightly Rust and the matching wasm-bindgen CLI:

rustup toolchain install nightly --component rust-src --target wasm32-unknown-unknown
cargo install wasm-bindgen-cli --version 0.2.127 --locked
bun run web

The generated Wasm uses shared memory, so the page must be cross-origin isolated. Production servers must send these headers on the top-level document:

Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: require-corp

require-corp then constrains cross-origin subresources, which must supply their own CORS or Cross-Origin-Resource-Policy. Serve the JavaScript and the Wasm from the same origin as the document and nothing else is needed.

bun run web rebuilds the Wasm only when packages/native/wasm is missing. After a Rust change, force it:

bun scripts/web.ts --rebuild

Hot reload in the browser

bun run web serves the example through Bun's frontend dev server, so an edit to examples/chat.tsx arrives as a React Fast Refresh update. Components swap in place and useState survives, which means the composer text, the sidebar selection, and the scroll position all stay where they were. The GPUI canvas is never re-created and the ~19 MB Wasm module is never re-fetched.

Fast Refresh only applies to a module whose exports are all components. Edit anything else, such as the entry file, and Bun reloads the page instead. Both paths are correct; the reload is only slower.

The Wasm half is a singleton and must never re-evaluate. WebGpuixRenderer::init fails with GPUIX web is already running once its thread-local app exists, and GPUI's browser platform appends its own canvas to <body>. What protects it is not that it lives in node_modules; Bun bundles it into the same client registry as your app. It is that Bun re-runs only the changed module and then walks upward through its importers, so an unchanged dependency stays evaluated and cached. Two rules follow:

• do not call import.meta.hot.accept("./your-app", ...) in the entry file. Bun runs an importer's dependency-accept callback even when the imported module already self-accepted, so that callback would remount the tree on top of a successful refresh and throw away every useState
• keep the @gpuix/native import in a module that can never become a Refresh boundary and is never explicitly accepted

The chat example puts a virtualized <diff> and a GFM table inside an assistant turn, inside a scrolling transcript:

Markdown, code and a virtualized diff in one frame:

Architecture

GPUIX bridges React to GPUI using a mutation-based protocol. Desktop apps use napi-rs; browser apps load the same Rust renderer through wasm-bindgen. React collects changed elements into one atomic mutation batch per commit. Rust applies that batch to a retained element tree that GPUI reads each frame.

┌─────────────────────────────────────────────────────────────────┐
│  React (JavaScript)                                             │
│                                                                 │
│  function App() {                                               │
│    const [count, setCount] = useState(0)                        │
│    return (                                                     │
│      <div style={{ display: 'flex', gap: 8 }}>                  │
│        <div onClick={() => setCount(c => c + 1)}>               │
│          Count: {count}                                         │
│        </div>                                                   │
│      </div>                                                     │
│    )                                                            │
│  }                                                              │
└─────────────────────────────────────────────────────────────────┘
                    │ napi desktop / wasm-bindgen browser
                    │ applyBatch([
                    │   ["createElement", 1, "div"],
                    │   ["setStyle", 1, {...}],
                    │   ["setRoot", 1]
                    │ ])
                    ▼
┌─────────────────────────────────────────────────────────────────┐
│  Rust host bridge                                               │
│                                                                 │
│  RetainedTree ── stores elements, styles, event flags           │
│       │                                                         │
│       ▼  each GPUI frame                                        │
│  GpuixView::render() → build_element() → GPUI elements          │
└─────────────────────────────────────────────────────────────────┘
                    │
                    ▼
┌─────────────────────────────────────────────────────────────────┐
│  GPUI                                                           │
│                                                                 │
│  Metal, DirectX, Vulkan, or browser WebGPU / WebGL2             │
│  Flexbox layout via Taffy                                       │
└─────────────────────────────────────────────────────────────────┘

Why This Works

GPUI is an immediate-mode UI framework — it rebuilds the entire element tree every frame. Instead of fighting this, GPUIX embraces it:

1. React reconciler detects a state change and queues host mutations (createElement, setStyle, appendChild, etc.)
2. applyBatch() validates and applies the complete commit to the Rust RetainedTree
3. On each GPUI frame, GpuixView::render() walks the RetainedTree and calls build_element() to produce ephemeral GPUI elements
4. GPUI lays them out (Taffy flexbox) and renders to the GPU
5. Only changed elements cross the FFI boundary — React's reconciler diffs the virtual tree and sends minimal mutations

This is the same protocol React uses for the DOM (createElement, appendChild, removeChild, commitUpdate), but targeting a GPU renderer instead of a browser.

Mutation API

The mutation surface between JS and Rust is one atomic method. Desktop uses napi and the browser uses wasm-bindgen:

interface NativeRenderer {
  applyBatch(json: string): Array<number>
}

Element IDs are plain numbers generated by an incrementing counter in JS. React may abandon work in concurrent render mode, so GPUIX keeps new host nodes in JS until React places the accepted subtree during commit. Only then are its mutations added to the batch. applyBatch() applies that accepted commit atomically and marks the Rust view dirty for the next frame.

Event Flow

On desktop, events travel from GPUI back to React through a ThreadsafeFunction callback. Browser event callbacks are not connected yet.

User clicks element id=3
       │
       ▼
GPUI fires on_click on the element
       │
       ▼
Rust closure calls emit_event_full(callback, 3, "click", {x, y, ...})
       │
       ▼
ThreadsafeFunction queues EventPayload on Node.js event loop
       │
       ▼
JS event registry: eventHandlers.get(3)?.get("click")?.(payload)
       │
       ▼
React handler runs: onClick={() => setCount(c => c + 1)}
       │
       ▼
State update triggers re-render → reconciler sends mutations back to Rust

Event handlers are stored in a JS-side registry keyed by (elementId, eventType). Rust only knows whether an element has a listener (via setEventListener), not the closure itself — the actual handler lives in JS.

Packages

• @gpuix/native — Rust bindings to GPUI. It publishes napi-rs desktop binaries and a wasm-bindgen browser build, both backed by GpuixRenderer, RetainedTree, build_element(), and apply_styles().
• @gpuix/react — React reconciler, event registry, and TypeScript types. Implements the react-reconciler host config using the mutation API.
• @gpuix/cli — gpuix new downloads example-app/, sets its published React dependency, and installs it as a standalone project.

Building

This section is for working on GPUIX itself. To build an app with it, see Quickstart instead. Installing the packages needs no Rust toolchain and no submodule.

Prerequisites

1. Rust toolchain
2. Node.js 18+
3. Xcode with Metal Toolchain (macOS)

# Install Metal Toolchain if needed
xcodebuild -downloadComponent MetalToolchain

# Install dependencies
bun install

# Check out the pinned GPUI fork
git submodule update --init --recursive

# Build native package
cd packages/native
bun run build

# Build React package
cd ../react
bun run build

# Run example (use tmux for long-running sessions)
cd ../../examples
bun --hot counter.tsx

Usage

import React, { useState } from 'react'
import { render } from '@gpuix/react'

function App() {
  const [count, setCount] = useState(0)
  return (
    <div style={{ display: 'flex', gap: 8, padding: 16 }}>
      <div
        style={{ backgroundColor: '#3b82f6', borderRadius: 8, padding: 12, cursor: 'pointer' }}
        onClick={() => setCount(c => c + 1)}
      >
        <div style={{ color: '#ffffff' }}>Count: {count}</div>
      </div>
    </div>
  )
}

render(<App />, {
  title: 'My App',
  width: 800,
  height: 600,
  titlebarTransparent: true,
  windowBackground: 'blurred',
  trafficLightX: 16,
  trafficLightY: 17,
})

render() creates the native window, mounts React, and starts the frame loop. The red traffic-light button quits the process. Start the app again from the terminal.

Call it again after a save and it remounts the tree on the same window.

The macOS menu bar

GPUIX installs the application menu bar for you, so a fresh app already answers ⌘Q, ⌘H, ⌥⌘H, ⌘M, and ⌘W. Without it NSApp.mainMenu is nil, macOS paints an empty menu bar, and those shortcuts do not exist at all: AppKit only provides them through menu items.

Apple    <executable>             Window
         ├ Services               ├ (AppKit window tiling)
         ├ Hide <appName>   ⌘H    ├ Minimize          ⌘M
         ├ Hide Others     ⌥⌘H    ├ Zoom
         ├ Show All               ├ Close Window      ⌘W
         └ Quit <appName>   ⌘Q    └ (open windows)

appName does not set the title of the application menu. macOS takes that from the executable, so bun app.tsx shows bun during development and a bun build --compile binary shows its own file name. Only a real .app bundle changes it. appName reaches the items inside the menu, and nothing else.

There is no Edit menu, on purpose. A menu key equivalent is consumed by AppKit before the window sees the key event, so an Edit menu carrying ⌘C would take the keystroke away from text selection and from <input>.

Use render(), not createRenderer(), in the app entry. bun --hot re-runs the whole file on save. createRenderer() plus init() would then build a second host. render() is idempotent: the first call owns the window, later calls only remount React.

createRenderer(), createRoot(), and startFrameLoop() stay public for tests and custom hosts. Pass { renderer } into render() when you already have one.

One renderer drives one root. A renderer owns one window, one native root id, and one event map, so createRoot() throws if that renderer already has a mounted root. Call unmount() on the first root before you create another; render() already does that for you.

Background launch

focus: false opens the window without taking focus. The app you were typing in keeps the caret and the active titlebar. show: false goes further and opens no window at all, so the process runs with a live React tree and nothing on screen.

render(<App />, { title: 'Notes', focus: false })

Turn this on whenever a coding agent runs your app. An agent that starts the app to check its work will otherwise yank the window in front of whatever you are doing, mid-sentence, once per iteration. With focus: false the agent still gets a real GPU-rendered window it can screenshot and click, and you keep your editor. See Let an agent drive the app.

activateWindow() brings the window forward and focuses it. It is the only way to reveal a show: false window. Reach it from any component with useGpuixRequired():

import { useGpuixRequired } from '@gpuix/react'

function Reveal() {
  const renderer = useGpuixRequired()
  return <div onClick={() => renderer.activateWindow?.()}>Show</div>
}

Outside React, call it on the renderer that createRenderer() returned.

The process still gets a Dock icon on macOS. GPUI sets the regular activation policy, so there is no menu-bar-agent mode yet. For a real background daemon, run the app from a launchd agent in ~/Library/LaunchAgents/; launchd never activates the process.

Let an agent drive the app

Make focus opt-in through the environment, so a human run behaves normally and an agent run stays out of the way:

render(<App />, {
  title: 'Notes',
  focus: process.env.GPUIX_BACKGROUND !== '1',
})

bun app.tsx                      # you: window comes to the front
GPUIX_BACKGROUND=1 bun app.tsx   # agent: window opens behind your editor

launch() passes env straight through, so an agent script sets it once and every screenshot, click, and assertion runs on a window that never interrupts you:

import { launch } from '@gpuix/react/automation'

const app = await launch({
  command: 'bun',
  args: ['app.tsx'],
  env: { GPUIX_BACKGROUND: '1' },
})

await app.getByTestId('bump').waitFor()
await app.getByTestId('bump').click()
await app.screenshot({ path: 'tmp/after-click.png' })
await app.close()

Focus is the only thing that changes. Automation does not need focus. click() hits the last painted bounds and screenshot() reads the GPU surface, so both work while the window sits behind your editor, and even on a show: false window that is not on screen at all.

  agent ──►  launch({ env: { GPUIX_BACKGROUND: '1' } })
                │
                ▼
           GPU window renders and paints without activation
                │
                ├──►  getByTestId(..).click()   ✓  hits the last painted bounds
                ├──►  screenshot({ path })      ✓  reads the GPU surface
                ├──►  fill() / press()          ✓  uses the live input pipeline
                └──►  close()

  you   ──►  keep typing, your editor stays frontmost the whole time

fill() and press() use the live GPUI window input pipeline. They work without activating the desktop window. Linux ignores focus, so an agent there still gets a focused window.

Prefer createTestRoot() when you can. It opens no window at all, so nothing can steal focus and keyboard input works. Reach for launch() plus focus: false when the check needs a real window, real GPU paint, or a real process.

flushSync

The root is a concurrent root, so React commits in a later microtask. flushSync forces the render and the commit to finish before it returns, the same as in react-dom.

import { flushSync } from '@gpuix/react'

flushSync(() => setSidebarOpen(true))

It flushes React only, down to one applyBatch call. After it returns the native retained tree is up to date, including styles and text.

It does not wait for GPUI. Layout and paint still happen on the next frame, exactly like the browser paints after a DOM mutation. To see pixels, wait a frame in the app, or call renderer.flush() in a test.

Use it when an ordering bug depends on the commit landing first: an unmount before a remount, or a state change before you feed the next event.

Debug frame overlay

GPUI paints frame-time stats into the window after layout. The overlay is not a React element. A React FPS label would update every frame and cause more work.

render(<App />, { title: 'My App', debugFrameOverlay: 'full' })

Or call the renderer:

renderer.setDebugFrameOverlay('full')
renderer.cycleDebugFrameOverlay()
renderer.resetDebugFrameOverlayStats()
renderer.getDebugFrameOverlay() // 'hidden' | 'minimal' | 'full'
renderer.getDebugFrameOverlayStats()
// { currentMs, p90Ms, p99Ms, maxMs, frames, samples }

p90Ms is the overlay 10% line. p99Ms is the 1% line. Those are the slow tail.

The overlay shows draw time, not FPS. 8.3 MS is about 120 Hz.

The chat example has a regression test for this: examples/chat.perf.test.tsx. It times mount, wheel draw, and sidebar clicks. It asserts p95, not every frame.

The default example suite excludes this hardware-timing test so shared CI runner variance does not fail functional checks. Run it explicitly on the target Mac:

On macOS, THROTTLE=utility restarts the process under taskpolicy -c utility. That pins work to E-cores. It is an M1/M2 Air CPU proxy, not Chrome 6x. GPU and RAM stay fast. THROTTLE=background is slower.

cd examples
THROTTLE=utility bun run test:perf
THROTTLE=utility bun --hot chat.tsx

Hot reload

1. End the file with render()

import { render } from '@gpuix/react'

function App() {
  return <div style={{ padding: 16 }}>hello</div>
}

render(<App />, { title: 'My App', width: 800, height: 600 })

Do not call createRenderer() or init() in this file. bun --hot re-runs the whole entry on save. A second init() would open a second window.

2. Start the app with bun --hot

Prefer bun --hot over a plain bun or tsx run. Without --hot, a save starts a second process. With it, render() remounts React on the same window.

bun --hot app.tsx
cd examples && bun --hot chat.tsx

3. Save the file

save .tsx  ►  bun re-evaluates the entry  ►  render() remounts React
                     │
                     ▼
              GpuixRenderer, window, GPU stay

The first render() creates the native host and stores it on globalThis. Each save unmounts the React tree and mounts a new one on that same host.

Stays: window, GPU device, native .node addon, GPUI scroll physics.

Resets: useState, focus, React event handlers.

This is a remount, not React Refresh. Keeping hook state needs Bun to inject $RefreshReg$ during --hot. That transform exists on bun build --react-fast-refresh only. Tracked in oven-sh/bun#40179.

Native .node edits still need a rebuild. See Developing the Rust side.

On macOS, startFrameLoop calls renderer.tick() at a fixed rate (~125fps by default). This pumps AppKit on the process main thread without blocking Node. Pass { frameMs } to change the rate, and call .stop() on the returned handle to end it.

On Windows and Linux, GPUI runs its normal blocking native event loop on one dedicated Rust UI thread. Node sends in-process commands to that thread, so startFrameLoop returns a no-op handle and does not create a JavaScript timer. All platforms use GPUI's native platform, window, renderer, input, scroll, clipboard, keyboard, and IME implementations. The embedded macOS run-loop extension comes from the pinned GPUIX fork. CI runs the full React and example test suites through DirectX on Windows.

Native animations

Use motion.div to animate from an initial style to a target style. React sends the target once. Rust calculates intermediate values and requests GPUI frames until the transition finishes, without a React render or N-API call for each frame.

Animate a target

import { motion } from '@gpuix/react'

function WelcomeCard() {
  return (
    <motion.div
      initial={{ width: 0, opacity: 0 }}
      animate={{ width: 320, opacity: 1 }}
      transition={{ duration: 0.25, ease: 'easeOut' }}
      style={{ overflow: 'hidden' }}
    >
      <text style={{ color: '#ffffff' }}>Welcome</text>
    </motion.div>
  )
}

Set initial={false} when the element must mount at its first animate target. Later animate changes still transition normally. If a target changes while motion is active, the next transition starts from the current visible value, so reversing an animation does not jump.

Targets and timing

Motion currently accepts these numeric targets:

The transition uses seconds, like Motion for React:

Springs, keyframes, variants, exit transitions, and shared layout animations are not available yet.

Animate a sidebar

Animate an outer clipping container and keep the inner sidebar at a fixed width. This reveals or hides the content without reflowing its text on every frame.

import { motion } from '@gpuix/react'
import type { ReactNode } from 'react'

function SidebarFrame({
  collapsed,
  children,
}: {
  collapsed: boolean
  children: ReactNode
}) {
  const sidebarWidth = 252
  const dividerWidth = 1

  return (
    <motion.div
      initial={false}
      animate={{ width: collapsed ? 0 : sidebarWidth + dividerWidth }}
      transition={{ duration: 0.2, ease: 'easeOut' }}
      style={{
        display: 'flex',
        flexDirection: 'row',
        height: '100%',
        flexShrink: 0,
        overflow: 'hidden',
      }}
    >
      <div style={{ width: sidebarWidth, height: '100%', flexShrink: 0 }}>
        {children}
      </div>
      <div style={{ width: dividerWidth, height: '100%', flexShrink: 0 }} />
    </motion.div>
  )
}

The chat example uses this pattern. The sidebar remains mounted while its outer width moves between 253 and 0 pixels.

Capture exact frames

The automation API can freeze the native motion clock and render specific timestamps. This avoids timer sleeps and gives CI the same frames on every run.

import { connectTest } from '@gpuix/react/automation'
import { createTestRoot } from '@gpuix/react/testing'
import { ChatApp } from './chat'

const { render, renderer } = createTestRoot()
render(<ChatApp />)
const app = await connectTest(renderer)

const startedAt = await app.clock.pause()
await app.getByTestId('sidebar-collapse').click()

await app.captureFrames('review/sidebar', [
  startedAt,
  startedAt + 50,
  startedAt + 100,
  startedAt + 150,
  startedAt + 200,
])

await app.clock.resume()

Scrolling

Containers with overflow: "scroll" become natively scrollable. GPUI handles scroll physics, clipping, and offset persistence automatically.

Plain scroll containers still build every child. Use <virtual-list> below when the collection can grow large.

function Expandable({
  preview,
  children,
}: {
  preview: React.ReactNode
  children: React.ReactNode
}) {
  const [open, setOpen] = useState(false)
  return (
    <div style={{ display: 'flex', flexDirection: 'column', gap: 8 }}>
      {open ? children : preview}
      {!open && <div onClick={() => setOpen(true)}>Show more</div>}
    </div>
  )
}

function ScrollableList() {
  return (
    <div style={{ height: 300, overflow: 'scroll' }}>
      {items.map((item, i) => (
        <div key={i} style={{ height: 60, padding: 12 }}>
          {item.name}
        </div>
      ))}
    </div>
  )
}

Per-axis scrolling: use overflowX: "scroll" or overflowY: "scroll". overflow: "scroll" scrolls both axes at once from a single diagonal gesture, like a browser.

A flex column stretches its children to the cross axis, so a two-axis container needs its rows to state a width. Without one there is nothing to pan on X:

<div style={{ width: 260, height: 220, overflow: 'scroll', display: 'flex', flexDirection: 'column' }}>
  {rows.map((row) => (
    <div key={row.id} style={{ display: 'flex', width: 810, flexShrink: 0 }}>
      {row.cells}
    </div>
  ))}
</div>

Panes that must move together

A native scroll container cannot drive a frozen header. GPUI moves the container on the wheel frame, and the JavaScript callback that would move the header arrives a frame later, so the header tears away during a fast pan.

When two panes must stay locked to the pixel, own the offset in React: put one onScroll listener on a non-scrolling parent, keep scrollX and scrollY in state, and translate each pane's content with an absolutely positioned wrapper. Zed does the same; the editor owns its scroll position and paints the gutter and the text from it.

function Pane({ offsetX, children }: { offsetX: number; children: React.ReactNode }) {
  return (
    <div style={{ flexGrow: 1, minWidth: 0, overflow: 'hidden', position: 'relative' }}>
      {/* An empty positioned box still takes hits, so opt it out. */}
      <div style={{ position: 'absolute', left: -offsetX, top: 0, pointerEvents: 'none' }}>
        {children}
      </div>
    </div>
  )
}

Keep the moving subtree in a memo component whose props do not change during a pan. The wheel then costs a handful of style mutations, not one per row. The timeline example does this for a ruler, a track column, and a clip grid.

For programmatic scroll control, use a React ref to get the element's numeric ID, then call the renderer's scroll methods:

function ProgrammaticScroll() {
  const listRef = useRef<any>(null)

  const jumpToBottom = () => {
    if (listRef.current) {
      renderer.scrollTo(listRef.current.id, 0, -999)
    }
  }

  return (
    <>
      <div ref={listRef} style={{ height: 200, overflow: 'scroll' }}>
        {items.map((item, i) => <div key={i}>{item}</div>)}
      </div>
      <div onClick={jumpToBottom}>Jump to bottom</div>
    </>
  )
}

// Available scroll methods on the renderer:
renderer.scrollTo(elementId, x, y)        // set offset directly
renderer.scrollToItem(elementId, index)   // scroll child into view
renderer.getScrollOffset(elementId)       // returns [x, y] or null

Virtual lists

Use <virtual-list> for long, variable-height collections such as message lists. React and Rust retain every row, but GPUI only builds, lays out, and paints rows near the viewport.

function MessageList({ messages }: { messages: Message[] }) {
  return (
    <virtual-list
      alignment="bottom"
      followTail
      estimatedItemHeight={180}
      style={{ flexGrow: 1, minHeight: 0 }}
    >
      {messages.map((message) => (
        <Message key={message.id} message={message} />
      ))}
    </virtual-list>
  )
}

The list needs a bounded height or bounded flex space. Its direct children are rows and can contain any GPUIX host or custom element.

How virtualization works

React reconciliation stays normal. The complete keyed child list crosses the mutation protocol and remains in Rust's retained tree. GPUIX defers only the expensive GPUI element construction, layout, and paint work.

React Fiber + Rust RetainedTree    all row IDs, props, text, and events
                 │
                 ▼
          GPUI ListState          row count and measured height cache
                 │
                 ▼ visible indexes plus overdraw
          cx.processor            re-enters GpuixView after root render
                 │
                 ▼
          fresh BuildCtx          builds only the requested React subtree
                 │
                 ▼
       GPUI layout and paint      visible rows only

Row heights

Rows do not need equal heights, and you do not need to know them. GPUI measures a row when it enters the viewport. estimatedItemHeight is a hint for rows nothing has measured yet, not a size contract.

index:     0        1        2        3        4        5        6        7
       ┌────────┬────────┬────────┬────────┬────────┬────────┬────────┬────────┐
       │  hint  │  hint  │measured│measured│measured│  hint  │  hint  │  hint  │
       │  220px │  220px │  184px │  512px │   96px │  220px │  220px │  220px │
       └────────┴────────┴────────┴────────┴────────┴────────┴────────┴────────┘
           ▲                          ▲                          ▲
           │                          │                          │
     estimate only         real, variable heights          estimate only
                          (viewport plus overdraw)

The sum of that height cache is the scroll length, so a rough estimate only affects scrollbar accuracy before a row is visited. The measured height replaces the estimate automatically, and the scrollbar converges as you scroll.

When a retained descendant changes, GPUIX marks its direct row for remeasurement, so a streaming row grows correctly. Appending, removing, or reordering keyed rows keeps measurements for rows whose IDs did not change.

estimatedItemHeight is optional in children mode, where every row exists and can be measured. It is required with itemCount, because React never mounts the rows outside the window and native has no element to measure. Those indexes render as an empty box of the estimated height until React mounts the real row.

Row boundaries

Each direct host child is one virtual row. Give every row a stable React key and one host root:

<virtual-list style={{ height: 500 }}>
  {messages.map((message) => (
    <div key={message.id} style={{ paddingBottom: 24 }}>
      <Message message={message} />
    </div>
  ))}
</virtual-list>

A row can contain nested <div>, <text>, <markdown>, <code>, <diff>, <input>, and <textarea> elements. Focusable rows stay active when they move offscreen, so keyboard input and native editor state are preserved. Those children must not scroll. Nested scrolling is not supported; see Scrolling.

Chat tail behavior

Combine alignment="bottom" and followTail for a chat thread:

<virtual-list
  alignment="bottom"
  followTail
  estimatedItemHeight={220}
  style={{ flexGrow: 1, minHeight: 0 }}
>
  {turns.map((turn) => (
    <ChatTurn key={turn.id} turn={turn} />
  ))}
</virtual-list>

The list follows new rows while the user is at the bottom. Scrolling upward pauses tail following. Returning to the bottom enables it again. A streaming final row is remeasured as its content grows.

Scroll anchoring

The list is anchored on a row index, not on a pixel offset. In children mode React reconciles by key, so that index still lands on the same row after a prepend: the rows already on screen stay exactly where they are. A browser does the same, and calls it scroll anchoring.

One exception, also copied from the browser: a top-aligned list that is scrolled to the very top stays at the top, so a prepended row is visible.

scrolled down                          pinned to the top
┌──────────────────┐                   ┌──────────────────┐
│ new row  (above) │  ◄── inserted     │ new row          │  ◄── inserted, visible
├──────────────────┤                   ├──────────────────┤
│ ░░ viewport ░░░░ │  stays put        │ ░░ viewport ░░░░ │  follows the insert
│ ░░░░░░░░░░░░░░░░ │                   │ ░░░░░░░░░░░░░░░░ │
└──────────────────┘                   └──────────────────┘

That is what a todo list or a feed wants: setItems((current) => [fresh, ...current]) puts the new row on screen. A history pane that loads older pages while the user reads should use alignment="bottom" instead, so a page load never moves the text.

With itemCount, the app owns the correction. There is no key to reconcile against, so the index is all there is. Prepending shifts every row down one slot, and the anchor keeps pointing at the old number, so the content slides by exactly the number of rows you inserted. Move windowStart by the same amount:

const prepend = (fresh: Row) => {
  setRows((current) => [fresh, ...current])
  // The anchor is an index. One new row above the window means every existing
  // row moved down one, so the window has to move with it.
  setWindowStart((start) => (start === 0 ? 0 : start + 1))
}

Leave windowStart at 0 alone; the list is pinned to the top there and the new row should be visible.

Programmatic scrolling

Use a ref to call the same renderer scroll methods as a plain scroll container:

function Results({ rows }: { rows: Result[] }) {
  const renderer = useGpuixRequired()
  const listRef = useRef<{ id: number } | null>(null)

  const reveal = (index: number) => {
    if (listRef.current) {
      renderer.scrollToItem?.(listRef.current.id, index)
    }
  }

  return (
    <>
      <virtual-list ref={listRef} style={{ height: 400 }}>
        {rows.map((row) => (
          <ResultRow key={row.id} row={row} />
        ))}
      </virtual-list>
      <div onClick={() => reveal(rows.length - 1)}>Reveal latest</div>
    </>
  )
}

scrollTo, scrollToItem, and getScrollOffset all support virtual lists.

On a virtual list, scrollToItem takes an optional pixel offset and the list reports its logical anchor:

renderer.scrollToItem(listId, index, offsetInItem)  // offset in px, may be negative
renderer.getListScrollTop(listId)  // [itemIndex, offsetInItemPx, viewportHeightPx] or null

A negative offset anchors the viewport top above the row, and the next layout resolves it against real measured heights. That is the tool for infinite-scroll history: while the reader waits in a loading row, read getListScrollTop, commit the fetched page, then re-anchor on the message that was under the loading row with a negative offset. The message stays at the same pixel while the new rows are measured above it — examples/infinite-chat.tsx is the worked example.

An itemIndex equal to the item count is gpui's at-end sentinel: a bottom-aligned list resting at its very end. A reader waiting at a trailing loading row usually sits there, and the viewport height in the same tuple is what converts that into a position relative to the trailing rows (EDGE_HEIGHT - viewportHeight in the example).

Virtual-list scrollToItem calls are applied on the next render, after that frame's child splice, so an index computed against a just-committed child list is never shifted twice.

Performance model

The children form still creates every React child, so a 10,000-row turns.map is slow to mount. Pass itemCount and windowStart and render only that slice to mount a window too. Collections with millions of rows still need application-level paging or a data-owning native element.

Keep scroll fast

A wheel event notifies the window view. GPUI then rebuilds the visible rows and Taffy lays them out again. Draw time is the cost of those rows, not the length of the list.

Put a long list on <virtual-list>. Keep overdraw near one extra viewport. Put fat content in one native node (<markdown>, <code>, <diff>), not a tree of React spans.

The host <virtual-list> still retains every React child. Pass itemCount, estimatedItemHeight and windowStart, then render only that window, so mount does not create every row. Native ignores itemCount when the estimate is missing, so a jump cannot collapse unmounted rows to height 0.

There is no VirtualList wrapper component. The window is app state: only the app knows when it must widen, for example when a filter grows itemCount without any scroll. Keep start in useState, move it from onVisibleRange, and slice around it.

const WINDOW = 40

const Transcript = memo(function Transcript({ turns }: { turns: Turn[] }) {
  const [start, setStart] = useState(0)
  const end = Math.min(turns.length, start + WINDOW)
  return (
    <virtual-list
      itemCount={turns.length}
      windowStart={start}
      estimatedItemHeight={220}
      style={{ flexGrow: 1, minHeight: 0 }}
      onVisibleRange={(event) =>
        setStart(Math.max(0, Math.floor(event.startIndex ?? 0) - WINDOW / 4))
      }
    >
      {turns.slice(start, end).map((turn) => (
        <ChatTurn key={turn.id} turn={turn} />
      ))}
    </virtual-list>
  )
})

function ChatApp() {
  const [collapsed, setCollapsed] = useState(false)
  const [turns, setTurns] = useState(initialTurns)
  return (
    <div style={{ display: 'flex', flexDirection: 'row', height: '100%' }}>
      <Sidebar collapsed={collapsed} onCollapse={() => setCollapsed(true)} />
      <Transcript turns={turns} />
      <Composer onSend={(text) => setTurns((current) => [...current, { text }])} />
    </div>
  )
}

turns is a new array only when a message arrives. Sidebar and draft updates leave that reference alone, so memo skips the map. The chat example uses this pattern.

overflowX: "scroll" on a wide child must not steal the vertical wheel. GPUIX sets restrict_scroll_to_axis on that path. Native overflow_x_scroll() must call the same method.

Turn on debugFrameOverlay: 'full' while you scroll. The overlay is draw time. 8.3 MS is about 120 Hz.

Pannable surfaces must cull

<virtual-list> is the only thing that virtualizes. A surface where you own the offset — a timeline, a node graph, a map — places its children absolutely, so GPUI builds and lays out every retained child on every frame. Nothing skips them for you.

memo and culling fix different halves, and only one of them is the draw:

memo(Layer)  ►  cuts React work and the applyBatch mutations
cull in JS   ►  cuts GPUI build, Taffy layout, and paint

You already know the offset, so the visible window is a useMemo away:

const visible = useMemo(() => {
  const from = scrollX / pxPerSecond
  const to = (scrollX + viewportWidth) / pxPerSecond
  return clips.filter((clip) => clip.start <= to && clip.start + clip.duration >= from)
}, [clips, scrollX, pxPerSecond, viewportWidth])

The timeline example measures both, on 3,259 clips across 26 tracks:

Text input

<input> and <textarea> use GPUI's platform input handler. They support a native caret, text selection, IME composition, clipboard actions, undo/redo, grapheme-safe deletion and mouse positioning.

<textarea
  value={draft}
  placeholder="Ask anything"
  minRows={1}
  maxRows={8}
  onChange={(event) => setDraft(event.value ?? '')}
  onSubmit={send}
/>

Enter emits onSubmit. In a <textarea>, Shift+Enter inserts a newline. The editor updates natively first, then reports the complete value to React. value changes can replace the native content, but keeping the same prop value does not reject an edit like a browser-controlled input.

The focused caret stays solid during edits and then blinks every 500ms while idle. It stops scheduling repaint frames on blur or while the window is inactive. Override its colour through the shared native theme:

<input theme={{ caret: '#22c55e' }} />

Focus and keyboard navigation

Focus is a native GPUI concept. GPUIX connects stable React element IDs to persistent gpui::FocusHandle values, so focus survives React rerenders:

React <div tabIndex={0}>
            │
            ▼
Retained element ID ► persistent gpui::FocusHandle ► keyboard/action dispatch
            ▲
            │
      React rerenders

Inputs and textareas join the normal tab order automatically. Add tabIndex to a div when it should receive keyboard focus:

<div
  tabIndex={0}
  onFocus={() => setActive(true)}
  onBlur={() => setActive(false)}
  onKeyDown={(event) => {
    if (event.key === 'enter') submit()
  }}
>
  Submit
</div>

Tab calls GPUI's window.focus_next(). Shift+Tab calls window.focus_prev(). This navigation stays in Rust and does not make a JavaScript round trip.

Use a ref for imperative focus:

const buttonRef = useRef<{ id: number }>(null)

function focusButton() {
  if (buttonRef.current) renderer.focusElement(buttonRef.current.id)
}

<div ref={buttonRef} tabIndex={-1}>Focused on demand</div>

Adding onKeyDown, onKeyUp, onFocus, or onBlur creates a persistent focus handle. Add tabIndex as well when the element must be reachable with Tab. Removing tabIndex removes the element from the tab order.

Headless controls

The built-in controls are unstyled primitives, not a fixed component library. Use them like Radix primitives in shadcn: import a primitive namespace, wrap and style it in a local file, then import those local components throughout the app.

@gpuix/react/select ► components/ui/select.tsx ► application screens
  native behavior       local styles/variants       product-specific use

Each primitive has a dedicated namespace entry point:

Build a local Select

Create components/ui/select.tsx. This file is application code, so it can be copied and changed without waiting for GPUIX to add a theme option:

import * as React from 'react'
import * as SelectPrimitive from '@gpuix/react/select'

export const Select = SelectPrimitive.Root
export const SelectValue = SelectPrimitive.Value
export const SelectGroup = SelectPrimitive.Group

export const SelectTrigger = React.forwardRef<
  React.ElementRef<typeof SelectPrimitive.Trigger>,
  SelectPrimitive.SelectTriggerProps
>(({ style, ...props }, ref) => (
  <SelectPrimitive.Trigger
    ref={ref}
    {...props}
    style={(state) => ({
      width: 220,
      height: 36,
      padding: 8,
      backgroundColor: state.open ? '#334155' : '#1e293b',
      borderRadius: 8,
      ...(typeof style === 'function' ? style(state) : style),
    })}
  />
))

export const SelectContent = React.forwardRef<
  React.ElementRef<typeof SelectPrimitive.Content>,
  SelectPrimitive.SelectContentProps
>(({ style, ...props }, ref) => (
  <SelectPrimitive.Content
    ref={ref}
    sideOffset={6}
    {...props}
    style={{
      width: 220,
      maxHeight: 240,
      overflowY: 'scroll',
      padding: 4,
      backgroundColor: '#0f172a',
      borderRadius: 8,
      ...style,
    }}
  />
))

export const SelectItem = React.forwardRef<
  React.ElementRef<typeof SelectPrimitive.Item>,
  SelectPrimitive.SelectItemProps
>(({ style, ...props }, ref) => (
  <SelectPrimitive.Item
    ref={ref}
    {...props}
    style={(state) => ({
      padding: 8,
      opacity: state.disabled ? 0.4 : 1,
      backgroundColor: state.highlighted
        ? '#334155'
        : state.selected
          ? '#1e3a5f'
          : '#0f172a',
      ...(typeof style === 'function' ? style(state) : style),
    })}
  />
))

Use the styled local file with the familiar shadcn shape:

import {
  Select,
  SelectContent,
  SelectGroup,
  SelectItem,
  SelectTrigger,
  SelectValue,
} from './components/ui/select'

<Select value={model} onValueChange={setModel}>
  <SelectTrigger>
    <SelectValue placeholder="Select a model" />
  </SelectTrigger>
  <SelectContent>
    <SelectGroup>
      <SelectItem value="sonnet">Sonnet</SelectItem>
      <SelectItem value="opus">Opus</SelectItem>
    </SelectGroup>
  </SelectContent>
</Select>

The trigger participates in normal tab navigation. Opening the Select focuses its content. Up, Down, Ctrl+P, Ctrl+N, Enter, and Escape control the menu. Closing it restores focus to the trigger. Disabled items are skipped.

Style Combobox and Tooltip the same way

Start their local files from namespace imports too:

// components/ui/combobox.tsx
import * as ComboboxPrimitive from '@gpuix/react/combobox'

// components/ui/tooltip.tsx
import * as TooltipPrimitive from '@gpuix/react/tooltip'

The application still uses compound components, not one large configuration object:

<ComboboxPrimitive.Root items={['Next.js', 'SvelteKit', 'Astro']}>
  <ComboboxPrimitive.Input style={{ width: 220, height: 36, padding: 8 }} />
  <ComboboxPrimitive.Content style={{ width: 220 }}>
    <ComboboxPrimitive.Empty>No frameworks found.</ComboboxPrimitive.Empty>
    <ComboboxPrimitive.List>
      {(item) => (
        <ComboboxPrimitive.Item key={item} value={item}>
          {item}
        </ComboboxPrimitive.Item>
      )}
    </ComboboxPrimitive.List>
  </ComboboxPrimitive.Content>
</ComboboxPrimitive.Root>

<TooltipPrimitive.Provider delayDuration={350}>
  <TooltipPrimitive.Root>
    <TooltipPrimitive.Trigger asChild>
      <div tabIndex={0} style={{ padding: 8 }}>Copy</div>
    </TooltipPrimitive.Trigger>
    <TooltipPrimitive.Content side="top" sideOffset={6}>
      Copy message
    </TooltipPrimitive.Content>
  </TooltipPrimitive.Root>
</TooltipPrimitive.Provider>

Combobox uses the native input for text editing, IME, clipboard, and focus. Tooltip asChild preserves the child ref and merges trigger behavior into that host element. All floating content uses GPUI's deferred anchored() layer, snaps inside the window, and occludes controls behind it.

Overlay menus

Menus, tooltips, and dialogs must use SelectContent, ComboboxContent, or <anchored deferred>. Those paint in a later pass, on top of <virtual-list> and the rest of the page.

A position: "absolute" card that overflows out of the composer sits under the virtual list. The list paints after the composer, so you still see the markdown through the menu, and clicks hit the text behind it.

<Select value={model} onValueChange={setModel}>
  <div style={{ position: 'relative' }}>
    <SelectTrigger>
      <SelectValue />
    </SelectTrigger>
    <SelectContent side="top" sideOffset={4} style={{ backgroundColor: '#232323' }}>
      <SelectItem value="flash">DeepSeek V4 Flash</SelectItem>
    </SelectContent>
  </div>
</Select>

Give every overlay an opaque fill (#232323, not #23232399). FloatingLayer defaults to #1A1A1A. Item rows should use the same solid color, or a solid hover color. A #00000000 child on a blurred window punches through Metal to the desktop.

A div that paints a fill, or that is positioned, blocks clicks and hovers behind it. The wheel still passes, so a pannable canvas can place its items absolutely and keep panning.

Set pointerEvents: "auto" on an element that must swallow the wheel too, like a modal backdrop. <anchored> occludes by default and has its own occlude prop, so menus and tooltips need neither.

pointerEvents: "none" means the element inserts no hitbox, so it blocks nothing behind it. It does not disable the listeners on that same element, and it does not inherit, so children keep their own hitboxes.

Text selection

Every text GPUIX paints is selectable and copyable, including text inside <code>, <diff> and <markdown>. A drag that starts in a heading and ends inside a fenced code block selects everything between; Cmd+C copies it joined in document order.

There is nothing to opt into. To opt out — toolbars, buttons, line-number gutters — set userSelect: "none", which inherits like the CSS property:

<div style={{ userSelect: 'none' }}>
  <text>toolbar label, never selected</text>
</div>

Read the selection from the renderer:

renderer.getSelectedText()   // joined text, or null
renderer.clearSelection()

Selection works because each painted text element registers itself into a per-frame registry in paint order, which is document order. A drag anchored in one element resolves against that registry into per-element spans: partial in the anchor and head, whole for everything between.

Text highlighting and search

The highlight prop paints a background wash behind matched text. Put it on any element and it applies to that element's subtree, so the root searches the window and a container searches only that container.

<div highlight={{ query: 'fox' }}>
  <text>the quick brown fox</text>
</div>

It reaches <text>, <code>, <markdown> and <diff> with no extra props, because every string GPUIX paints goes through the same funnel.

A find bar

useTextSearch owns the cursor and the count. next and previous are plain event handlers, so nothing here needs an effect.

import { useTextSearch } from '@gpuix/react'

function Find() {
  const [query, setQuery] = useState('')
  const search = useTextSearch({ query })

  return (
    <div style={{ display: 'flex', flexDirection: 'column', flex: 1 }}>
      <div style={{ display: 'flex', gap: 8, alignItems: 'center' }}>
        <input value={query} onChange={(e) => setQuery(e.value ?? '')} />
        <text>{search.total === 0 ? 'No results' : `${search.active + 1}/${search.total}`}</text>
        <div onClick={search.previous}><text>↑</text></div>
        <div onClick={search.next}><text>↓</text></div>
      </div>

      <div {...search.props} style={{ flex: 1 }}>
        <Transcript />
      </div>
    </div>
  )
}

Explicit ranges

When you already have offsets, from an LSP range or your own model, pass them instead of a query. They are [start, end) in UTF-16 code units, the units indexOf and RegExp.exec return.

<div highlight={{ ranges: [[6, 11]], color: '#f43f5e55' }}>
  <text>Hello {name}!</text>
</div>

A pair that splits a surrogate pair is rejected, never snapped. Ranges index retained text only; native elements build their strings in Rust, so use query for those.

Options

Pass an array to paint several at once, for example search matches plus a persistent mention tint. Later entries draw on top.

Matching rules

Matches are non-overlapping and leftmost-first. Case-insensitive matching uses Unicode lowercasing, not full case folding, so ff does not match ff. A word boundary is any code point that is not Unicode Alphabetic, a digit, or _.

A match never crosses a line, exactly like browser find. It does cross the several host nodes React creates for one interpolated line, which matters more than it sounds:

// React makes 3 host text nodes here. `Hello Tommy` still matches.
<div highlight={{ query: 'Hello Tommy' }}>
  <text>Hello {name}!</text>
</div>

The nearest declaration wins, so a nested highlight replaces its ancestor's for that subtree.

userSelect: "none" does not opt out of search. A browser still finds that text, so GPUIX still highlights it. Only element chrome, a code gutter or a diff file header, is excluded.

import { findRanges, useTextSearch } from '@gpuix/react'

// One entry per row, so a prefix sum gives both numbers.
const perRow = useMemo(
  () => rows.map((row) => findRanges({ text: row.text, query }).length),
  [rows, query],
)

const search = useTextSearch({
  query,
  matches: {
    total: perRow.reduce((n, count) => n + count, 0),
    indexOffset: perRow.slice(0, windowStart).reduce((n, count) => n + count, 0),
  },
})

// search.next() moves the cursor; you do the scrolling
listRef.current.scrollToItem(rowOfMatch(search.active))

Native text components

Three elements render text with Syntect syntax highlighting computed in Rust. Colours come from a theme prop, so a late-arriving highlight recolours runs without ever changing layout.

<code>

A syntax-highlighted code block. One row per line at an exact line height, so the block's height is known before highlighting runs.

It paints no surface of its own: no fill, border, radius, padding or language header. style is the surface, so the card look is yours.

<code
  code={source}
  language="typescript"        // or path="src/app.ts" to detect from extension
  showLineNumbers
  style={{
    padding: 12,
    borderRadius: 10,
    borderWidth: 1,
    borderColor: '#ffffff1f',
    backgroundColor: '#ffffff09',
  }}
/>

fontFamily, fontSize, fontWeight, lineHeight and color in style beat the theme. Rows are a fixed height, so fontSize alone scales that height by the theme's ratio; pass lineHeight to set it exactly.

Two things stay owned by the element: lines never wrap, and the block is its own horizontal scroller. A long line pans on a horizontal wheel inside it, so whiteSpace and overflowX in style do nothing.

For a language header, or any other chrome, wrap it in a <div> you own:

<div style={{ display: 'flex', flexDirection: 'column', borderRadius: 10, overflow: 'hidden' }}>
  <div style={{ padding: 6, backgroundColor: '#ffffff09' }}>
    <text style={{ fontSize: 12, color: '#a3a3a3' }}>{language}</text>
  </div>
  <code code={source} language={language} style={{ padding: 12, minWidth: 0 }} />
</div>

<markdown> is different: it keeps its own fenced-block card, because a document renderer owns its layout. Tune that card with the mdCode* metrics.

<diff>

A unified diff viewer. It flows with its parent by default, so a parent list can be the only scroller. Collapsing a file removes its rows rather than hiding them, so a collapsed 10k-line file costs one row.

Use maxLines to keep a long patch short. Show more fires onShowMore. Clear maxLines in that handler to reveal the rest.

Pass scroll and a bounded height only for a dedicated full-window viewer. That path uses GPUI's list() and virtualizes. Do not nest it inside another scroller. See Scrolling.

<diff
  patch={unifiedPatch}
  wordDiff                     // highlight only the tokens that changed
  maxLines={open ? undefined : 24}
  collapsedPaths={['pnpm-lock.yaml']}
  onShowMore={() => setOpen(true)}
  onToggleFile={(e) => toggle(e.value)}
  onLineClick={(e) => console.log(e.oldLine, e.newLine, e.value)}
/>

<markdown>

GitHub-flavoured markdown: headings, lists, tables, block quotes, fenced code, strikethrough, task lists, and autolinked bare URLs.

<markdown source={readme} onLinkClick={(e) => open(e.value)} />

Theming

All three take the same optional theme prop. Every field layers on top of the built-in dark theme, so overriding one token leaves the rest alone.

<code
  code={source}
  language="rust"
  theme={{
    appearance: 'dark',        // or 'light'
    accent: '#7c86ff',
    syntax: { keyword: '#f38ba8', string: '#a6e3a1' },
  }}
/>

Layout numbers live in the theme too, under metrics. Row heights, gutter widths, paddings and the heading scale are props, not Rust constants, so tuning the design is a React re-render and never a native rebuild.

<diff
  patch={patch}
  theme={{
    metrics: {
      diffLineHeight: 26,
      diffGutterWidth: 48,
      mdHeadingSizes: [24, 19, 16, 14],
    },
  }}
/>

When scroll is on, <diff> virtualizes from these numbers without measuring, so changing diffLineHeight also re-sizes the scroll model.

The same three components, retuned entirely from metrics with no rebuild:

Languages bundled: Rust, TypeScript, TSX, JavaScript, JSX, Python, Go, JSON, Bash, TOML, YAML, Markdown, HTML, CSS, C.

Supported Elements

Images and icons

<img> takes a filesystem path, not a URL. Resolve the file with fileURLToPath or path.join and pass that string as src.

<img>

<img> paints through GPUI's image element. It loads PNG, JPEG, WebP, GIF, and SVG from disk. SVG here is a full-colour image, not a tintable icon.

<img
  src={fileURLToPath(new URL('./photo.png', import.meta.url))}
  objectFit="cover"
  style={{ width: 240, height: 140, borderRadius: 12 }}
/>

objectFit matches CSS: "contain" (default), "cover", "fill", "scaleDown", or "none". An empty src or a failed load shows a fallback placeholder instead of crashing.

<svg>

<svg> uses GPUI's monochrome icon renderer. Raw source works on desktop and in the browser. Desktop apps can also use a local src path. The icon is drawn as one shape and tinted with style.color.

For application icons, prefer raw SVG source. It works with both GPUIX targets and lets a bundler embed each icon in the JavaScript bundle. Use src only for a desktop app that intentionally ships loose asset files.

src is a filesystem path or a data:image/svg+xml,… URL. Vitest and some Bun import … with { type: 'file' } bindings emit the data URL. GPUIX decodes both.

style.color is required. Without it the icon does not paint. Prefer fill="#000" or stroke="#000" in the file. currentColor in the SVG is not the same as style.color.

Bun

Use Bun's text loader. The import is a string containing the complete SVG, and bun build embeds it in the bundle.

import searchSvg from './assets/icons/search.svg' with { type: 'text' }

<svg
  source={searchSvg}
  style={{ width: 16, height: 16, color: '#b4b4b4' }}
/>

The chat example builds every sidebar and composer icon from raw SVG source this way.

Node.js

For supported Node.js releases, read the icon once relative to the module. A URL keeps the path correct across operating systems and avoids __dirname.

import { readFileSync } from 'node:fs'

const searchSvg = readFileSync(
  new URL('./assets/icons/search.svg', import.meta.url),
  'utf8',
)

<svg
  source={searchSvg}
  style={{ width: 16, height: 16, color: '#b4b4b4' }}
/>

Node.js also has text modules, but they currently require --experimental-import-text. Prefer readFileSync until text imports no longer need a runtime flag.

Supported Events

Keyboard and focus listeners create a persistent GPUI FocusHandle automatically. A listener alone does not put a div in the Tab order; add tabIndex={0} for that. Inputs and textareas already use tab index 0.

A node that listens for both onMouseDown and onMouseMove captures the pointer, like HTML setPointerCapture. onMouseMove and onMouseUp keep firing after the pointer leaves the hitbox, leaves the parent, and leaves the window. A node with only onMouseDown / onMouseUp does not capture, so a click still ends if you release outside.

Capture is armed by the press itself, so put all three listeners on the element the user grabs:

<div
  style={{ cursor: 'grab', active: { cursor: 'grabbing' } }}
  onMouseDown={(e) => beginDrag(e)}
  onMouseMove={(e) => moveDrag(e)}
  onMouseUp={endDrag}
/>

A full-window overlay mounted on the press cannot replace this. The overlay does not exist yet when the press happens, so it never arms capture, and a release past the window edge is lost. Only the pressed element receives moves while the gesture runs, and only the hovered element receives them otherwise, so the cost is one event per pointer move.

Capture arms on the left button only. A right-button drag is not captured, so it ends when the pointer leaves the element.

onClick is the primary button too, like the DOM. Use onAuxClick for the others, and read event.isRightClick. onMouseDown and onMouseUp see every button through event.button (0 left, 1 middle, 2 right).

Supported Styles

CSS-like styling via the style prop:

<div style={{
  display: 'flex',
  flexDirection: 'column',
  gap: 8,
  padding: 16,
  backgroundColor: '#3b82f6',
  borderRadius: 8,
}}>
  <div style={{ color: '#ffffff', fontSize: 18 }}>
    Hello GPUI!
  </div>
</div>

Layout: display ("flex" | "grid"), flexDirection, flexWrap, flexGrow, flexShrink, flexBasis, alignItems, alignSelf, alignContent, justifyContent, gap, rowGap, columnGap, gridTemplateColumns, gridTemplateRows, gridColumnMin, gridRowMin

Sizing: width, height, minWidth, minHeight, maxWidth, maxHeight — accepts pixels (number) or percentages (string like "100%")

Spacing: padding, paddingTop/Right/Bottom/Left, margin, marginTop/Right/Bottom/Left

Position: position ("relative" | "absolute" | "fixed"), top, right, bottom, left — "fixed" lays out like "absolute", because GPUI has no scrolling document to be fixed against

Visual: background, backgroundColor, color, opacity, cursor, pointerEvents, borderRadius, borderTopLeftRadius, borderTopRightRadius, borderBottomLeftRadius, borderBottomRightRadius, borderWidth, borderTopWidth, borderRightWidth, borderBottomWidth, borderLeftWidth, borderColor, boxShadow

Cursors

cursor takes the CSS keyword. An unlisted keyword is ignored, like any other invalid style value.

<div style={{ cursor: 'grab', active: { cursor: 'grabbing' } }} />
<div style={{ cursor: 'col-resize' }} />

Colors

Every color-bearing style field accepts the same string grammar. GPUIX native uses csscolorparser 0.8.3 and accepts:

• named colors and transparent;
• 3/4/6/8-digit hex, with or without #;
• rgb() / rgba(), hsl() / hsla(), hwb() / hwba(), and hsv() / hsva();
• lab(), lch(), oklab(), and oklch();
• none components and the parser's limited relative-color from / calc() forms.

Standard comma and modern space/slash alpha forms work. Values are converted to hard-clipped sRGB before GPUI paints them. Invalid strings are ignored for that property; they do not reject the full style object.

Linear gradients

background accepts GPUI's native two-stop linear gradient. Angles follow CSS: 0 points up and values increase clockwise. Stop positions use 0 to 1.

<div
  style={{
    background: {
      type: 'linear-gradient',
      angle: 90,
      stops: [
        { color: '#7c3aed', position: 0 },
        { color: '#06b6d4', position: 1 },
      ],
      colorSpace: 'oklab',
    },
    borderRadius: 12,
  }}
/>

colorSpace is optional and defaults to "srgb". GPUI also supports "oklab". It does not support radial, conic, repeating, or gradients with more than two stops.

hsv(), hsva(), and hwba() are parser extensions rather than CSS Color 4 standard functions. color(), platform/dynamic colors, and numeric color integers are not accepted.

Theme values can use the same modern grammar:

const theme = {
  surface: 'oklch(18% 0.02 260)',
  accent: 'oklch(67.3% 0.182 276.935)',
  text: 'oklch(96% 0 0)',
}

<div style={{ backgroundColor: theme.surface, borderColor: theme.accent }}>
  <text style={{ color: theme.text }}>Hello GPUIX!</text>
</div>

Limited relative-color forms can derive a new color from a base value:

<div
  style={{
    backgroundColor: '#bad455',
    borderColor: 'oklch(from #bad455 calc(l - 0.15) calc(c * 0.7) h)',
  }}
/>

boxShadow accepts one structured shadow. Its fields are offsetX, offsetY, blurRadius, spreadRadius, and color:

<div
  style={{
    boxShadow: {
      offsetX: 0,
      offsetY: 4,
      blurRadius: 12,
      spreadRadius: 0,
      color: '#00000033',
    },
  }}
/>

Overflow: overflow, overflowX, overflowY — "hidden" clips content, "scroll" creates a native scrollable container with persistent scroll state

Text: fontSize, fontFamily, fontWeight, textAlign, lineHeight, whiteSpace, textOverflow, lineClamp

Selection: userSelect ("text" | "none"), selectionColor — both inherit down the tree

Hover and active

hover and active are nested style objects. GPUI applies them natively when the pointer is over the element or the mouse is down. There is no JavaScript round trip.

<div
  style={{
    backgroundColor: '#313244',
    borderRadius: 8,
    padding: 12,
    hover: { backgroundColor: '#45475a' },
    active: { backgroundColor: '#585b70' },
  }}
>
  Press
</div>

Nesting is one level deep. A hover object cannot contain another hover or active.

They work on every element, including <text>, <code>, <markdown>, <diff>, <img>, <svg> and the editors. The one exception is <virtual-list>, whose style type rejects them: gpui's list has no interactive identity to hold a hovered or pressed state, so put them on a wrapping <div>.

Note: white-space: pre is not supported. GPUI's text system only has normal (wraps) and nowrap (single line). To preserve newlines like HTML <pre>, split your text on \n in React and render each line as a separate <text> element in a flex column:

<div style={{ display: 'flex', flexDirection: 'column', fontFamily: 'Menlo' }}>
  {code.split('\n').map((line, i) => (
    <text key={i} style={{ whiteSpace: 'nowrap' }}>{line}</text>
  ))}
</div>

Note: GPUI defaults text color to black, not white. Unlike CSS, GPUI does not inherit color from parent elements. Every <text> element that doesn't set an explicit color style will render as black — invisible on dark backgrounds. Always set color on your text elements or on a parent <div> (which applies text_color to all children in that subtree via GPUI's Styled trait).

Automation

Mark elements with testId, then drive them like Playwright. The same client works in vitest, inside browser pages, and against a child process.

<div testId="sidebar-collapse" onClick={onCollapse}>‹</div>
<textarea testId="composer" value={draft} onChange={...} />
<div testId="send" onClick={onSend}>↑</div>

import { createTestRoot } from '@gpuix/react'
import { connectTest } from '@gpuix/react/automation'
import { ChatApp } from './chat'

const { render, renderer } = createTestRoot()
render(<ChatApp />)
const app = await connectTest(renderer)

await app.screenshot({ path: 'open.png' })

await app.clock.pause()
await app.getByTestId('sidebar-collapse').click()
await app.clock.fastForward(200)
await app.screenshot({ path: 'collapsed.png' })

await app.getByTestId('composer').fill('hello gpuix')
await app.getByTestId('send').click()
await app.screenshot({ path: 'sent.png' })

That is the chat example. The real test lives in examples/chat.test.tsx.

createTestRoot()          browser render()          launch({ command, args })
       │                         │                              │
       ▼                         ▼                              ▼
connectTest(renderer)      globalThis.gpuix                child stdin / stdout
       │                         │                              │
       └─────────────────────────┴──► App / Locator ◄───────────┘
                                  click, fill, query, clock

Browser apps

Every browser render installs the automation App as globalThis.gpuix. It is always available after render() returns. No setup flag or separate transport is required.

await page.evaluate(async () => {
  await globalThis.gpuix
    .getByTestId('sidebar-collapse')
    .click()

  await globalThis.gpuix
    .getByTestId('composer')
    .fill('hello from Playwriter')

  await globalThis.gpuix.clock.pause()
  await globalThis.gpuix.clock.fastForward(200)
})

The browser global supports locators, input, tree and text queries, bounds, selection, scrolling, focus, and clock control. Browser pages cannot write an arbitrary local screenshot path. Use the controlling browser tool for that:

await page.screenshot({ path: 'review/chat.png', scale: 'css' })

Bounds come back in canvas pixels, not CSS pixels, because that is the coordinate space GPUI lays out in. On a 2x display a locator at x: 44 sits at CSS x: 22. Convert before handing a rectangle to a browser tool:

const scale = await page.evaluate(() => {
  const canvas = document.querySelector('canvas')!
  return canvas.width / canvas.clientWidth
})
const { bounds } = await page.evaluate(() =>
  globalThis.gpuix.getByText('New Task').waitFor(),
)
await page.screenshot({
  scale: 'css',
  clip: {
    x: bounds.x / scale,
    y: bounds.y / scale,
    width: bounds.width / scale,
    height: bounds.height / scale,
  },
})

Do not read window.devicePixelRatio for this. An automation tool can override the viewport scale factor after GPUI has already sized its canvas, and then the two disagree.

Locators

click() hits the center of the last painted bounds. fill(text) replaces the focused editor contents. press('enter') sends one key. waitFor() polls until exactly one match exists. textContent() returns the node's own text plus every descendant's, like DOM textContent.

Mouse, wheel, and drag

A drag sends interpolated moves, not one jump, because snapping, live previews, and per-move commits only appear when the pointer travels. Pass steps to control how many, and offset to press away from the center.

await app.getByTestId('clip-7').dragBy(120, 0, { steps: 6 })
await app.getByTestId('clip-7-trim-end').dragTo(app.getByTestId('clip-8'))
await app.mouse.drag({ x: 240, y: 500 }, { x: 700, y: 620 })

Every mouse call takes modifiers in the same syntax as press('cmd-a'), so cmd-wheel zoom, shift-click range selection, and alt-drag duplication are all testable:

await app.getByTestId('canvas').wheel(0, 120, { modifiers: 'cmd' })
await app.getByTestId('clip-8').click({ modifiers: 'shift' })

click() needs painted bounds. Every element that accepts testId records them, including <img>, <svg> and <anchored>. An <anchored> reports the box of the overlay itself, not of the trigger it is anchored to, so click() lands on the menu even when it is deferred and snapped back inside the window.

<virtual-list> is the exception, and it takes no testId. gpui's list is not an interactive element, so it has nothing to record a box against. Put the locator on a wrapping <div>.

Screenshots and clock

app.screenshot({ path }) writes the current GPU frame as a PNG.

app.clock.pause(), set(ms), and fastForward(ms) freeze native motion time. Use that to capture a sidebar animation at known timestamps:

const startedAt = await app.clock.pause()
await app.getByTestId('sidebar-collapse').click()
await app.captureFrames('review/sidebar', [
  startedAt,
  startedAt + 100,
  startedAt + 200,
])

Live apps

launch({ command, args }) starts the app and speaks the same commands over stdin as SSE data: lines. The app listens only when stdin is a pipe, so a normal terminal run is unchanged. Lines without a data: prefix are ignored; console.log cannot break a message.

import { launch } from '@gpuix/react/automation'

const app = await launch({
  command: 'bun',
  args: ['examples/chat.tsx'],
  env: { GPUIX_BACKGROUND: '1' },
})
await app.getByTestId('composer').fill('hello')
await app.getByTestId('composer').press('enter')
await app.getByText('hello').waitFor()
await app.screenshot({ path: 'live.png' })
await app.close()

Every live-app check must set GPUIX_BACKGROUND=1, and the app entry must map that flag to focus: false. On macOS and Windows, automation uses the real window input and paint pipelines without making the window active, so taking the user's keyboard has no test benefit. Linux currently ignores focus.

fill() and press() dispatch through the live GPUI window input pipeline, so native <input> and <textarea> elements receive GPUI's keyboard and IME handling instead of a test-only input path.

Testing

The locators above sit on a GPU-backed test renderer (TestGpuixRenderer). It runs the same GpuixView, build_element(), apply_styles(), and event handlers as production. Test windows are positioned offscreen and rendered by Metal on macOS or DirectX on Windows. The methods below are the lower-level API when a locator is not enough.

import { createTestRoot } from '@gpuix/react/testing'

const { root, renderer } = createTestRoot()

root.render(<MyComponent />)
renderer.flush()  // triggers GpuixView::render() on the native GPU

// Simulate events through GPUI's native input pipeline
renderer.nativeSimulateClick(50, 50)
renderer.nativeSimulateKeystrokes('enter')

// Inspect results
const events = renderer.drainNativeEvents()
renderer.captureScreenshot('/tmp/test.png')
const text = renderer.getAllText()

Testing native elements

getAllText() only sees <text> nodes in the retained tree. <code>, <diff> and <markdown> paint their text inside GPUI, so use getPaintedText(), which returns every string painted in the last frame in paint order:

root.render(<code code={'a\nb'} language="ts" />)
expect(renderer.getPaintedText()).toEqual(['a', 'b'])

Selection has its own helper. Listeners are registered during paint, so dragSelect flushes between every step; calling simulateMouseDown / Move / Up by hand without those flushes selects nothing:

expect(renderer.dragSelect(20, 30, 900, 300)).toBe('first line\nsecond line')

A highlight is a quad, so no amount of getPaintedText() will show it. Use getPaintedHighlights(), which reports the matched range in UTF-16 units plus the boxes it actually drew, one per visual row:

root.render(
  <div highlight={{ query: 'quick' }}>
    <text>the quick brown fox</text>
  </div>,
)
const [hit] = renderer.getPaintedHighlights()
expect(hit.text.slice(hit.start, hit.end)).toBe('quick')
expect(hit.rects).toHaveLength(1)

Assert numbers, not pixels

For a stateful surface, paint the state you want to assert into a readout element and read it with textContent(). A screenshot tells you that something changed; a readout tells you what, and the failure message names the number.

<text testId="readout">{`x=${scrollX} y=${scrollY} zoom=${zoom} sel=${selected}`}</text>

const readout = await app.getByTestId('readout').textContent()
expect(readout).toBe('x=140 y=60 zoom=24 sel=clip-7')

Every test in examples/timeline.test.tsx works this way, including the drag, trim, snap, and zoom gestures. Keep the screenshot as well, for a human to look at after the run.

Screenshots land in packages/react/screenshots/ and examples/screenshots/, both gitignored, so they can be inspected after a run without adding a binary diff to every commit. The curated set the README links to lives in docs/images/ and is regenerated with:

bun scripts/screenshots.ts

Developing the Rust side

JS remount is covered above. There is no hot reload for the native half, and there cannot be: require() of a .node file calls process.dlopen, Node has no matching unload, and the live state (GPUI's platform, GPU device, open window, UI thread, and selection registry) stays inside the loaded library. A second load would create independent native state while the first library remains loaded.

The rebuild is fast enough that it does not matter. Measured on an M-series Mac after touching one file:

bun run dev wires that into a loop: it watches packages/native/src, rebuilds, and re-renders the screenshot tests. Rust edit to fresh PNGs is about 4 seconds.

bun run dev                      # rebuild, re-render the showcase screenshots
bun scripts/dev.ts --shots diff  # only tests matching "diff"
bun scripts/dev.ts --app native-text   # rebuild, restart an example app

Screenshot mode is the better default. Open packages/react/screenshots/showcase.png in Preview.app, which reloads on write, and unlike a live window the PNG can also be read by an agent.

Two things avoid the rebuild entirely:

• Content already lives in props. Change patch or source and the next frame shows it.
• Design numbers live in theme.metrics. Tuning a row height or heading scale is a React re-render.

The test renderer uses VisualTestAppContext with a TestDispatcher for deterministic scheduling. Event simulation goes through GPUI's coordinate-based hit testing and dispatch — not synthetic JS events.

Status

• React reconciler with mutation-based protocol
• Atomic applyBatch() mutation transport through napi-rs and wasm-bindgen
• RetainedTree (Rust-side element storage)
• Style mapping (CSS properties → GPUI style methods)
• Mouse events (click, mouseDown, mouseUp, mouseMove, mouseEnter, mouseLeave)
• Click outside (onMouseDownOutside)
• Scroll wheel events with delta and touch phase
• Scrollable containers (overflow: "scroll") with persistent scroll state
• Programmatic scroll API (scrollTo, scrollToItem, getScrollOffset)
• Keyboard events (keyDown, keyUp) with focus management
• Focus/blur events with automatic FocusHandle creation
• GPU-backed test renderer with screenshot capture
• Standalone build (pinned GPUI platform dependencies)
• Native text input and multiline textarea
• Image and SVG elements (<img>, <svg>)
• Virtual lists (<virtual-list>)
• Native text components (<code>, <diff>, <markdown>)
• Cross-element text selection
• Text highlighting and search (highlight, useTextSearch)
• Headless Select, Combobox, and Tooltip
• Native hover and active styles
• Window title (setWindowTitle)
• Window chrome (titlebarTransparent, windowBackground, traffic-light position)
• macOS menu bar with the standard shortcuts (appName)
• App-declared menus and menu callbacks
• Background launch (focus, show, activateWindow)
• Last window close quits the process
• Debug frame overlay (debugFrameOverlay / setDebugFrameOverlay)
• Canvas element
• Multiple windows
• JS remount under bun --hot (render() keeps the native window)
• React Refresh during bun --hot (needs a Bun runtime transform)
• Hot reload of the native .node addon. bun run dev rebuilds and restarts. Native modules cannot unload.
• Native motion.div transitions with deterministic frame capture

Documentation

See AGENTS.md for detailed architecture, communication flow, and contributing guide.

License

Apache-2.0