PyModel/pythinker-code / .agents/skills/opentui
opentui
VerifiedBuild terminal UIs with OpenTUI. Covers core, components, audio, keymaps, React, Solid, plugins, testing, standalone executables, QR encoding, SSH, and Three.js WebGPU.
docs/plugins/react.mdx
View on GitHub---
title: React
description: React slot components backed by the shared plugin registry
order: 3
---
# React slots
This page shows React integration for plugin slots.
Use slots when you want external modules to contribute `ReactNode` UI in host-defined regions without forking your app. The host keeps ownership of layout and slot typing; plugins only see the context and props you expose.
If you have not read the shared model yet, start with [Plugin Slots](/docs/plugins/slots).
## Runtime-loaded external plugins
If your app loads plugins from disk at runtime (for example `await import(fileUrl)`), add this import once in your app entry:
```ts
import "@opentui/react/runtime-plugin-support"
```
This installs Bun runtime support so external TS/TSX plugin modules resolve against the host runtime instances (`@opentui/react`, React JSX runtime modules, and core runtime modules).
Use this for plugin systems in both normal Bun runs and standalone compiled executables.
```ts
import "@opentui/react/runtime-plugin-support"
const mod = await import(pathToFileURL(pluginPath).href)
registry.register(mod.loadExternalPlugin())
```
If plugins need additional host-resolved modules, configure runtime support before the side-effect import is loaded:
```ts
import { ensureRuntimePluginSupport } from "@opentui/react/runtime-plugin-support/configure"
ensureRuntimePluginSupport({
additional: {
"my-runtime-module": { marker: "ok" },
},
})
```
First-party packages expose side-effect-free runtime module maps. For plugins that import `@opentui/three`, install `@opentui/three` in the host app and pass its runtime modules explicitly:
```ts
import { runtimeModules as threeRuntimeModules } from "@opentui/three/runtime-modules"
import { ensureRuntimePluginSupport } from "@opentui/react/runtime-plugin-support/configure"
ensureRuntimePluginSupport({
additional: threeRuntimeModules,
})
```
The side-effect import and configurable entrypoint install the same runtime plugin. Late additions throw with a clear error instead of being ignored.
## What React adds
- `createReactSlotRegistry(renderer, context, options?)` — create a registry typed for `ReactNode`. Accepts the same [`SlotRegistryOptions`](/docs/plugins/slots#registry-options) as `createSlotRegistry`.
- `Slot<TSlots, TContext>` — generic slot component that takes `registry` as a required prop
- `createSlot(registry, options?)` — optional convenience helper that returns a registry-bound `<Slot />` component
- `ReactPlugin<TSlots, TContext>` — convenience type alias for a plugin that returns `ReactNode`
- `@opentui/react/runtime-plugin-support` — one-line runtime support for external plugin/module loading
- `@opentui/react/runtime-plugin-support/configure` — configurable runtime support without import-time side effects
Register plugins directly with `registry.register()` — no wrapper function is needed (unlike core's `registerCorePlugin`).
## Basic usage
```tsx
import { createCliRenderer } from "@opentui/core"
import { createReactSlotRegistry, createRoot, Slot } from "@opentui/react"
type Slots = {
statusbar: { user: string }
}
const context = { appName: "react-app", version: "1.0.0" }
const renderer = await createCliRenderer()
const registry = createReactSlotRegistry<Slots, typeof context>(renderer, context)
const unregister = registry.register({
id: "clock-plugin",
slots: {
statusbar(ctx, props) {
return <text>{`${ctx.appName}:${props.user}`}</text>
},
},
})
const AppSlot = Slot<Slots, typeof context>
function App() {
return (
<AppSlot registry={registry} name="statusbar" user="sam" mode="replace">
<text>fallback-statusbar</text>
</AppSlot>
)
}
createRoot(renderer).render(<App />)
```
## Optional convenience helper
If you prefer not to pass `registry` each time, you can still bind one once:
```tsx
const AppSlot = createSlot(registry)
```
## `<Slot>` props
| Prop | Type | Required | Description |
| -------------------------- | ------------------------------------------ | -------- | ---------------------------------------------------------------------------------------------------------- |
| `registry` | `SlotRegistry<ReactNode, Slots, Context>` | yes | Registry to resolve plugins from |
| `name` | `keyof Slots` | yes | Which slot to render |
| `mode` | `SlotMode` | no | `"append"` (default), `"replace"`, or `"single_winner"`. See [slot modes](/docs/plugins/slots#slot-modes). |
| `pluginFailurePlaceholder` | `(failure: PluginErrorEvent) => ReactNode` | no | Per-slot placeholder UI when a plugin throws |
| `children` | `ReactNode` | no | Fallback UI |
| _remaining_ | `Slots[name]` | — | Slot-specific props forwarded to plugin renderers |
## `ReactSlotOptions` (for `createSlot`)
| Option | Type | Required | Description |
| -------------------------- | ------------------------------------------ | -------- | ------------------------------------------- |
| `pluginFailurePlaceholder` | `(failure: PluginErrorEvent) => ReactNode` | no | Creates placeholder UI when a plugin throws |
## Plugin failure placeholders
```tsx
const Slot = createSlot(registry, {
pluginFailurePlaceholder(failure) {
return <text>{`plugin-error:${failure.pluginId}:${failure.phase}`}</text>
},
})
```
If a plugin throws, the slot renders the placeholder. If no placeholder is provided (or it returns `null`), the slot falls back to `children`.
Plugins that throw during the initial render call are caught inline. Plugins that throw during a React re-render are caught by an internal error boundary that resets on registry changes.
## Observability
```tsx
registry.onPluginError((event) => {
console.error(event.pluginId, event.phase, event.source, event.error.message)
})
```
Example: `packages/react/examples/plugin-slots-errors.tsx`
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |