Skip to main content

Display

ComposedSurface

Draws Ouro's composed tree with Ouro HX, whatever format it came in: core's ComposedNode, from A2UI messages, an MCP tool result's structuredContent.ouro, or your own code. Every button is one of your app's declared actions: read and write run, a consequential one asks the person to confirm what the agent prepared, and a person-only one takes them to your app's own screen.

A shallow pan of golden orzo with peas and charred lemon halves

Charred Lemon Orzo

Orzo toasted in brown butter, finished with charred lemon and peas. A weeknight pan dinner.

VegetarianOne pan
Time
25 min
Servings
4

Press a button.

Install

Once per app, with Tailwind CSS v4 and an @/* path alias (Ouro HX is built on Base UI, so --base base; skip -t in an existing app):

npx shadcn@latest init --base base --preset nova --yes --no-monorepo
npx shadcn@latest add ourostack/ouro-ui/ouro-base#v1.3.258

Then the component. From v0.8.0 it installs only the helpers it imports and never touches your stylesheet (Installing):

npx shadcn@latest add ourostack/ouro-ui/composed-surface#v1.3.258

Or, with the @ouro namespace set up:

npx shadcn@latest add @ouro/ouro-base @ouro/composed-surface

Its tests, stories and Playwright spec are optional. They need Vitest 4.1.11 or later, and from v0.8.0 never change a version your app has (Testing):

npx shadcn@latest add ourostack/ouro-ui/composed-surface#v1.3.258 ourostack/ouro-ui/composed-surface-tests#v1.3.258
import { ComposedSurface } from "@/components/ouro/composed-surface/composed-surface";

Paths use shadcn's default @/ alias; the CLI rewrites them to yours.

Example

<ComposedSurface
  tree={result.structuredContent.ouro.tree}
  onPress={(press) => callTool(press.action, press.input)}
  onHandoff={({ action }) => navigate(`/recipes/${id}?do=${action}`)}
/>

Use instead when

  • Use A2UISurface instead for A2UI messages, and HX's components directly when your own code, not an agent, decides the layout.

Props

Type: ComposedSurfaceProps.

className
Type: string
Layout only: margins, width (max-w-md).
onHandoff (required)
Type: (handoff: ComposedHandoff) => void
A person-only button never runs from composed UI: take the person to your app's own screen for it.
onPress (required)
Type: (press: PersonPress, button: ComposedNode) => void | Promise<void>
Runs a pressed read or write button, and a consequential one once the person confirms. press is core's PersonPress (the action, the prepared input, its consent, and that the person pressed it); button is the node, for a format that names its source. Return a promise to show the button loading until it settles.
tree (required)
Type: ComposedNode
The composed tree to draw: core's ComposedNode, its values resolved. Check one you didn't resolve yourself with core's validateTree against the app's catalog first; A2UI's resolver already has.

Don't use

These are not props. Passing one fails the type check with the fix in the error, and in development a console message names the fix.

  • onAction: Not a prop. A pressed button calls onPress, or onHandoff for a person-only one: <ComposedSurface onPress={run} onHandoff={openApp}>.

className is for layout only

Pass margins, width and grid placement (mt-4, w-full, col-span-2).

Appearance comes from props, not classes. In development, a class that sets appearance logs one warning per component instance, naming the prop to use instead. A class sets appearance when, after its variants (hover:, sm:) and any ! are removed, it starts with bg-, text-, border-, rounded-, shadow-, font-, ring-, from-, via-, to-, fill- or stroke-, or is border, rounded, shadow or ring, or has a dark: variant. Text wrapping, overflow and table layout classes (text-wrap, text-ellipsis, border-collapse) are layout and do not warn.

Alignment classes (text-center) warn too: set alignment on a parent element.

Types

ComposedHandoff

Where a person-only button takes the person: the action's id and the catalog's how.

interface ComposedHandoff {
  action: string;
  how: string;
}