Plugin slots

Most TUI apps start as one codebase. As features and teams grow, you may want extension points without asking users to fork the app.

Plugin slots give you that. The host application defines named places in the layout (for example, a status bar, sidebar, or panel), and plugins contribute UI for those places at runtime.

The host stays in control of layout, rendering mode, and type contracts. Plugins only receive the context and slot props the host intentionally exposes.

This page describes the shared registry API that the core, React, and Solid bindings are built on. If you are building an app, start with the page for the binding you use:

• Core slots — framework-free, BaseRenderable nodes
• React slots — ReactNode
• Solid slots — JSX.Element

If you load plugin modules from disk at runtime, see the runtime support notes on the React slots page and Solid slots page. For custom hosts, use @opentui/core/runtime-plugin-support or createRuntimePlugin from @opentui/core/runtime-plugin.

Read on if you need to understand the underlying model, want to build a custom binding for another framework, or need direct access to the registry API.

Concepts

• Host: defines slot names and slot prop types.
• Plugin: contributes one or more slot renderer callbacks. May include lifecycle hooks.
• Registry: registers plugins and resolves contributions for a slot.
• Slot mode: controls how plugin output and fallback UI combine (append, replace, or single_winner).

Define slots and host context

Slot names map to the props each slot receives. The host context is a shared object passed to every plugin renderer.

import type { PluginContext } from "@opentui/core"

type AppSlots = {
  statusbar: { user: string }
  sidebar: { section: "left" | "right" }
}

interface AppContext extends PluginContext {
  appName: string
  version: string
}

The context can be any object. PluginContext is a type alias for object — extending it is not required but gives your plugins a named type to reference.

Create a registry

import { createSlotRegistry } from "@opentui/core"

const context = { appName: "my-app", version: "1.0.0" }

const registry = createSlotRegistry<string, AppSlots, typeof context>(renderer, "my-app:plugins", context)

The first type parameter (TNode) is the node type your framework returns — BaseRenderable for core, ReactNode for React, JSX.Element for Solid. The framework-specific helpers fill this in for you.

createSlotRegistry is renderer-scoped. For a given (renderer, key) pair, you always get the same registry instance. The key parameter namespaces registries within a renderer so multiple independent registries can coexist.

Calling createSlotRegistry again with the same (renderer, key) pair returns the existing registry and applies the new options via configure(). The context argument must be the same object reference — passing a different context object throws an error. This means you should create the context object once and reuse it:

// correct — same object reference
const context = { appName: "my-app" }
const reg1 = createSlotRegistry(renderer, "my-key", context)
const reg2 = createSlotRegistry(renderer, "my-key", context) // returns reg1

// throws — different object even if structurally identical
const reg3 = createSlotRegistry(renderer, "my-key", { appName: "my-app" })

When the renderer is destroyed, all registries scoped to it are automatically cleared and disposed.

The framework-specific helpers (createCoreSlotRegistry, createReactSlotRegistry, createSolidSlotRegistry) call createSlotRegistry internally with a fixed key. Use createSlotRegistry directly only if you need multiple independent registries per renderer.

Registry options

All create*SlotRegistry functions accept an optional SlotRegistryOptions object:

Register plugins

const unregister = registry.register({
  id: "clock-plugin",
  order: 0,
  setup(ctx, renderer) {
    // called once on registration — initialize resources here
  },
  dispose() {
    // called when the plugin is unregistered — clean up resources here
  },
  slots: {
    statusbar(ctx, props) {
      return `${ctx.appName}:${props.user}`
    },
  },
})

// later: remove this plugin
unregister()

register() returns an unregister function. Calling it removes the plugin and invokes its dispose hook.

Plugin interface

The core binding extends this with managed slot objects that add lifecycle hooks.

Ordering

Plugins are resolved in this order:

1. order ascending (lower numbers first)
2. Registration order (earlier registrations first)
3. id lexicographic (tie-breaker)

Slot modes

Every slot mount or <Slot> component accepts a mode. The mode controls how plugin output and fallback UI combine.

Resolve contributions

const entries = registry.resolveEntries("statusbar")
// Array<{ id: string, renderer: (ctx, props) => TNode }>

const slotRenderers = registry.resolve("statusbar")
// Array<(ctx, props) => TNode>

renderer here means the plugin’s slot renderer callback, not the CliRenderer instance.

Use resolveEntries when you need plugin ids alongside the callbacks. Use resolve when you only need the callbacks.

Registry methods

Error handling

Registries expose plugin error events:

registry.onPluginError((event) => {
  console.error(event.pluginId, event.phase, event.source, event.error.message)
})

You can also read and clear buffered errors:

const history = registry.getPluginErrors()
registry.clearPluginErrors()

PluginErrorReport

The reportPluginError method accepts a PluginErrorReport:

PluginErrorEvent

Next: concrete host APIs

Use the shared model above with one of these host integrations:

• Core slots — framework-free, returns BaseRenderable nodes
• React slots — returns ReactNode
• Solid slots — returns JSX.Element