@corbits/react-ui

React components for agent products: conversations with reasoning, tool calls and approvals, run status, artifacts and charts, styled by one Tailwind v4 token theme. The UI package of Corbits: it renders data a host web app loads from Interchange, and works in any React 18 or 19 app without Interchange.

Why @corbits/react-ui?

1. Props in, markup out. No component fetches, subscribes or holds a client. Your data layer stays yours, and every component renders the same in stories, tests and production.
2. Agent-shaped building blocks. Message holds a turn while Tool, Reasoning and Activity render its parts (text, reasoning, tool calls), ToolApproval asks a person before a call runs, and GateBlock and StepList cover a run that waits on a person.
3. Pay for what you import. One root entry, the package is side-effect free apart from its CSS, and heavy peers (Radix dialog, dropdown-menu, tooltip, sonner) are optional.
4. Server Components ready. Stateful modules ship "use client", so a React Server Components app imports them directly. Outside RSC the directive is a no-op.

Install

bun add @corbits/react-ui react react-dom lucide-react @radix-ui/react-slot

Requires Node 24 or later. Tested on React 19; the peer range also accepts React 18.2+.

Optional peers are needed only by the modules that import them. Those modules are not in the root entry, so import them by subpath:

Quickstart

Import the stylesheet once at the app root, before your own CSS, and mount ThemeProvider near the root:

import "@corbits/react-ui/styles.css";

import {
  Activity,
  Conversation,
  ConversationContent,
  ConversationItem,
  ConversationScrollButton,
  Message,
  MessageContent,
  MessageHeader,
  ThemeProvider,
  groupActivity,
  type ConversationMessage,
  type ConversationParticipant,
} from "@corbits/react-ui";

const you: ConversationParticipant = { id: "u1", kind: "person", name: "You" };
const scout: ConversationParticipant = {
  id: "a1",
  kind: "agent",
  name: "Scout",
};

const messages: ConversationMessage[] = [
  {
    id: "m1",
    author: you,
    at: "2026-01-01T09:00:00Z",
    status: "sent",
    parts: [{ kind: "text", text: "What changed in the repo today?" }],
  },
  {
    id: "m2",
    author: scout,
    at: "2026-01-01T09:00:04Z",
    status: "sent",
    parts: [
      {
        kind: "reasoning",
        text: "Check the commit log first.",
        durationMs: 1200,
      },
      {
        kind: "tool-trace",
        toolCallId: "t1",
        name: "git__log",
        status: "output-available",
        output: "3 commits",
      },
      { kind: "text", text: "Three commits landed today, all in the docs." },
    ],
  },
];

function Turn({ message }: { message: ConversationMessage }) {
  const own = message.author.id === you.id;
  return (
    <Message
      from={own ? "own" : message.author.kind}
      status={message.status}
      aria-label={own ? "You" : undefined}
    >
      {own ? null : (
        <MessageHeader name={message.author.name} at={message.at} />
      )}
      {groupActivity(message.parts).map((group) => {
        if (group.kind === "activity")
          return <Activity key={group.key} steps={group.steps} />;
        if (group.part.kind === "text")
          return <MessageContent key={group.key} text={group.part.text} />;
        return null;
      })}
    </Message>
  );
}

export function App() {
  return (
    <ThemeProvider>
      <div style={{ display: "flex", flexDirection: "column", height: 480 }}>
        <Conversation>
          <ConversationContent>
            {messages.map((message) => (
              <ConversationItem key={message.id} itemId={message.id}>
                <Turn message={message} />
              </ConversationItem>
            ))}
          </ConversationContent>
          <ConversationScrollButton />
        </Conversation>
      </div>
    </ThemeProvider>
  );
}

This renders the user message in a bubble, the agent's thinking and tool call folded into one activity line that opens onto both, and the agent's reply. Every other part kind (tool calls waiting on a person, images, sources, files) has its own component; see Chat.

styles.css includes Tailwind preflight and a base layer, so it restyles the page. If you already run Tailwind v4, import @corbits/react-ui/theme.css instead and let your build generate the utilities. Import one of the two, never both; without either, components render unstyled.

Where it fits

• Interchange runs AI agents as principals (first-class identities with their own permissions and credentials). The hub is its multi-tenant control plane: tenants, principals, grants (permissions a principal holds) and credentials. The sidecar is the portable agent runtime.
• Corbits is the set of published packages around Interchange that turn an agent into a product. This package is the UI bucket: it runs in the host web app and plugs into the host's data layer, not into the hub or the sidecar.
• It pairs with the hub modules whose data it renders, such as @corbits/artifacts, @corbits/mailbox and @corbits/cron.

Reference

Import from the root; it tree-shakes to what you use. Only the optional-peer modules have their own subpath:

import { Button } from "@corbits/react-ui";
import { Toaster, toast } from "@corbits/react-ui/ui/toast";

export function SignOut() {
  return (
    <>
      <Button onClick={() => toast("Signed out.")}>Sign out</Button>
      <Toaster position="bottom-right" />
    </>
  );
}

Theming

Dark mode is a .dark class on an ancestor. With neither .dark nor .light on the root, the tokens follow prefers-color-scheme and set color-scheme for native controls; dark: utilities still need a .dark ancestor.

ThemeProvider toggles both classes and persists the choice under storageKey. Hosts that manage the class themselves add .light for an explicit light choice, since removing .dark falls back to the OS. To avoid a dark first paint for a stored light choice on a dark OS, add .light before first paint only when the stored choice is light:

<script>
  if (localStorage.getItem("corbits-theme")?.includes('"light"'))
    document.documentElement.classList.add("light");
</script>

The theme names Red Hat Display and Space Mono but does not bundle them. Load them yourself or the stack falls back to system fonts; override --font-sans and --font-mono for a face loaded under another name.

Components

Everything imports from @corbits/react-ui, except rows marked "optional peer", which import from the subpath shown; see Install.

Chat

Runs

Artifacts

Charts

Layout

Controls

For coding agents

The package ships an agent skill: a short guide, usage rules and a props reference for every component. Point your agent at node_modules/@corbits/react-ui/skills/react-ui (start with SKILL.md), or copy that folder into your agent's skills directory.

Using with Interchange

The host app owns the connection to the hub; components only take props.

1. Load run state with @intx/hub-client: createRunSession polls a workflow run's event log and exposes a seq-ordered WorkflowRunEvent timeline.
2. Map that timeline to props: agent output to ConversationMessage parts rendered by Message inside a Conversation, a tool call waiting on a person to a PartTool carrying its ToolApprovalRecord for ToolApproval, step events to StepList items, and a run parked on a person to GateBlock.
3. Wire callbacks back to the hub. ToolApproval's onDecide calls your hub route that resolves the awaited approval with the decision's outcome and scope; the hub checks the caller's grant, not the component. The settled record comes back on the part, and ToolApproval shows what was decided.

Upgrading from 0.3

The old chat family is removed. The conversation family replaces it: a message is a ConversationMessage whose parts are a ConversationPart[] (discriminated by kind), and the components are built from parts you compose rather than one component per screen.

• Part, PartText, PartReasoning, PartToolTrace, PartBlock, PartFile, PartEvent and ToolTraceStatus are unchanged and still import from the root.

Removed exports and what replaces them:

Upgrading from 0.1

• Install from npm. Git installs (github:corbitsdev/react-ui#<sha>) no longer build dist/.
• Per-module subpaths are gone: import from @corbits/react-ui (import { Button } from "@corbits/react-ui").
• ui/dialog, ui/command-palette, ui/sidebar-search, ui/mic-permission-dialog, ui/menu, ui/tooltip and ui/toast are subpath-only, and their peers are optional: import { Toaster, toast } from "@corbits/react-ui/ui/toast". Install the peer for each subpath you keep.
• lib/csv, lib/url, lib/utils, lib/workflow-registry and ui/chat-dock-timing (removed in 0.4) are internal. Replace cn with twMerge(clsx(...)).
• Stateful components ship "use client". Client wrappers you wrote for them still work, and can go.
• 84 unused modules are removed, ui/command is removed, ActivityBlock is renamed ReasoningBlock (removed in 0.4; use Reasoning, see Upgrading from 0.3), and AuthLayout no longer renders DitherCanvas by default.
• With neither .dark nor .light on the root, the theme follows the OS. Hosts that toggle .dark must add .light for an explicit light choice, or mount ThemeProvider.

License

LGPL-2.1-only. See LICENSE.