Skip to content

Components ​

Everything a plugin shows in the conversation or a surface is built from these components, and everything they produce is A2UI. The app draws each one natively, so they always match the app and adapt to light and dark mode, text size and device.

Preview

This is version 0 of the component set, designed in the open. Components and props may change before the first release.

tsx
import { Card, Row, Column, Text, Metric, Badge, Button, Icon } from '@agentplaygrounds/sdk'

Two catalogs ​

A2UI groups components into catalogs. The SDK's components come from two:

  • Basic: the A2UI basic catalog, with the same names and props. UI built only from basic components works in any A2UI app.
  • Agent Playgrounds: our catalog, a strict superset of basic. It adds components like Metric and Terminal, and optional props on some basic components, like tone on Text. Every basic surface is also valid in it.

Each table below shows which catalog a component or prop comes from. The Where column shows where it can be used: in blocks in the conversation, in views like surfaces, inspector tabs and view commands, or in slots like a sidebar row. Slots are specific to Agent Playgrounds and aren't A2UI. See How UI works.

Layout ​

ComponentCatalogWhereWhat it's for
CardBasic, with additionsBlocks, viewsThe main container for a block
ColumnBasicBlocks, viewsArranges children top to bottom
RowBasicBlocks, viewsArranges children side by side
ListBasicBlocks, viewsA scrolling list of children, often ListItems
TabsBasicViewsSwitches between titled panes
ModalBasicBlocks, viewsOpens content in a sheet when its trigger is used
DividerBasicBlocks, viewsA thin line between groups

Card ​

tsx
<Card title="Lisbon" subtitle="Clear" icon={Icon.CloudSun} accessory={<Badge tone="success">Live</Badge>}>
  …
</Card>
PropCatalogTypeDescription
childrenBasicComponentsThe card's content. In A2UI a card has one child, so the SDK wraps several in a Column for you.
titleAgent PlaygroundsstringThe card's heading
subtitleAgent PlaygroundsstringA short line under the title
iconAgent PlaygroundsIconShown beside the title
accessoryAgent PlaygroundsBadge or TextShown at the trailing edge of the title row
actionsAgent PlaygroundsButton elementsThe first is shown on the card; the rest are in its … menu

Column and Row ​

PropCatalogTypeDescription
justifyBasic"start", "center", "end", "spaceBetween", "spaceAround", "spaceEvenly" or "stretch"Distribution along the main axis
alignBasic"start", "center", "end" or "stretch"Alignment across it

Rows wrap onto more lines when there isn't room, such as on iPhone.

List ​

PropCatalogTypeDescription
directionBasic"vertical" (default) or "horizontal"
alignBasic"start", "center", "end" or "stretch"
isLoadingAgent PlaygroundsbooleanShows a loading state instead of an empty list
searchableAgent PlaygroundsbooleanViews only. Adds a search field that filters ListItems by title and keywords.
paginationAgent Playgrounds{ hasMore, onLoadMore }Views only. Loads more as people scroll.

Tabs, Modal and Divider ​

ComponentProps
Tabstabs: { title, content }[]
Modaltrigger: a component, usually a Button; content: what opens
Divideraxis: "horizontal" (default) or "vertical"

Content ​

ComponentCatalogWhereWhat it's for
TextBasic, with additionsBlocks, views, slotsA heading, line or paragraph of plain text
ImageBasicBlocks, viewsA picture from a URL
IconBasic, with additionsBlocks, views, slotsA symbol
VideoBasicBlocks, viewsA video from a URL
AudioPlayerBasicBlocks, viewsAudio from a URL
MarkdownAgent PlaygroundsBlocks, viewsRich text: headings, lists, links, inline code
CodeAgent PlaygroundsBlocks, viewsHighlighted code with a copy button
BadgeAgent PlaygroundsBlocks, views, slotsA short colored label, like "Merged" or "Stalled"
MetricAgent PlaygroundsBlocks, viewsA big number with a label
ProgressAgent PlaygroundsBlocks, views, slotsA progress bar, or a spinner when the amount is unknown
FactsAgent PlaygroundsBlocks, viewsLabel and value pairs, like a summary of a pull request
ListItemAgent PlaygroundsBlocks, viewsA row with a title, icon and accessories
TableAgent PlaygroundsBlocks, viewsRows and columns of data

Text ​

PropCatalogTypeDescription
childrenBasicstringThe text. Sent as A2UI's text.
variantBasic"h1" to "h5", "body" (default) or "caption"
toneAgent PlaygroundsToneDefaults to "primary"
linesAgent PlaygroundsnumberTruncates after this many lines

Image ​

PropCatalogTypeDescription
urlBasicstringAn https URL your plugin may reach, or a file in assets/
descriptionBasicstringRequired by the SDK. Read aloud by VoiceOver and shown if the image can't load.
fitBasic"contain", "cover", "fill", "none" or "scaleDown"
variantBasic"icon", "avatar", "smallFeature", "mediumFeature", "largeFeature" or "header"Size and shape, chosen by the app to fit the context

Icon ​

PropCatalogTypeDescription
nameBasicIconAn icon from the SDK's Icon list, which includes every basic catalog icon
symbolAgent PlaygroundsstringAny SF Symbol name, like "figure.walk", for icons not in the list

Wherever a prop takes an Icon, pass a name from the list, like Icon.CloudSun.

Video and AudioPlayer ​

ComponentProps
Videourl
AudioPlayerurl, description

Markdown and Code ​

ComponentProps
Markdownchildren: CommonMark, with tables and task lists. Links go through the app's link policy.
Codechildren: the code; language: for highlighting, like "ts"

Badge ​

PropTypeDescription
childrenstringOne or two words
toneToneDefaults to "neutral"
iconIcon

Metric ​

PropTypeDescription
valuestringThe number, already formatted, like "21°" or "1,204"
labelstringWhat it measures
trend"up", "down" or "flat"Shows an arrow next to the value
toneTone

Progress ​

PropTypeDescription
valuenumber from 0 to 1Leave it out for an indeterminate spinner
labelstringLike "Uploading"
toneTone

Facts ​

tsx
<Facts
  items={[
    { label: 'Author', value: 'mira', icon: Icon.Person },
    { label: 'Checks', value: 'Passing', tone: 'success' },
    { label: 'Branch', value: 'pricing-page', url: 'https://github.com/…' },
  ]}
/>

Each item has label, value, and optional icon, tone and url.

ListItem ​

tsx
<List>
  <ListItem
    title="Fix broken links"
    subtitle="#482"
    icon={Icon.PullRequest}
    accessories={[{ badge: 'Review', tone: 'warning' }, { date: pr.updatedAt }]}
    actions={<Button action={openUrl(pr.url)}>Open</Button>}
  />
</List>
PropTypeDescription
titlestringRequired
subtitlestring
iconIcon
keywordsstring[]Extra words to match when searching
accessoriesAccessory[]Shown at the trailing edge: { text }, { badge, tone } or { date }, shown relative, like "2h"
actionsButton elementsThe first runs when the row is clicked; the rest are in its context menu

Table ​

PropTypeDescription
columns{ key, title, align? }[]
rowsRecord<string, string>[]

Rich content ​

From the Agent Playgrounds catalog. Each can open into a larger surface.

ComponentWhereProps
TerminalBlocks, viewstext, title, status: "running", "succeeded" or "failed". Follows the tail as output streams in.
MapBlocks, viewspins: { id, title, latitude, longitude }[], route: [latitude, longitude][], title
WebPageBlocks, viewsurl, title. A link card that opens in a safe browser.
DiffBlocks, viewsChanges to files, with additions and deletions. Coming soon.

Buttons and actions ​

Button is how people act. It's a basic catalog component: its label is a child, and its action either runs a handler in your plugin or calls a function in the app.

tsx
<Button variant="primary" onAction={async (block) => block.update(await getWeather(city))}>
  Refresh
</Button>

<Button action={openUrl('https://example.com')}>Open Website</Button>
PropCatalogTypeDescription
childrenBasicstring or componentsThe label. A string becomes a Text child.
variantBasic"default", "primary" or "borderless"
onActionBasic(context) => void | Promise<void>Your handler. The SDK sends it as an A2UI action event, and runs it when the action comes back. In a block, context is the block, with update(payload) and room.
actionBasicA function callRuns in the app without a round trip: openUrl(url), copyToClipboard(text) or openSurface(name, props)
checksBasicCheck functionsDisables the button until every check passes, like [required('/form/title')]
iconAgent PlaygroundsIconShown before the label
destructiveAgent PlaygroundsbooleanShown in red, and asks for confirmation first
shortcutAgent PlaygroundsShortcutA keyboard shortcut, like { modifiers: ['cmd'], key: 'r' }. Prefer Shortcut.Common.

openUrl is from the basic catalog and always goes through the app's link policy. copyToClipboard and openSurface are from ours.

Forms ​

Form fields come from the basic catalog. Each one binds to a path in the surface's data model and updates it as people type; the values go to your handler when a button's action fires.

tsx
<Form onSubmit={(values) => createIssue(values)} submitTitle="Create Issue">
  <TextField name="title" label="Title" checks={[required()]} />
  <TextField name="body" label="Details" variant="longText" />
  <ChoicePicker
    name="label"
    label="Label"
    variant="mutuallyExclusive"
    options={[{ value: 'bug', label: 'Bug' }, { value: 'idea', label: 'Idea' }]}
  />
  <CheckBox name="urgent" label="Urgent" />
</Form>
ComponentCatalogWhat it's for
TextFieldBasicText. variant: "shortText" (default), "longText", "number" or "obscured"
CheckBoxBasicOn or off
ChoicePickerBasicOne choice, or several with variant="multipleSelection". displayStyle: "checkbox" or "chips".
DateTimeInputBasicA date, a time, or both, with min and max
SliderBasicA number between min and max

Form is SDK shorthand, not an A2UI component: it lays fields out in a Column, binds each name to /form/<name> in the data model, and adds a submit Button that sends them. Use it in views, not in blocks.

Checks come from the basic catalog: required(), email(), regex(pattern), length({ min, max }) and numeric().

Shared types ​

Tone ​

"primary", "secondary", "neutral", "accent", "success", "warning" or "danger". Tones are meanings, not colors: the app picks colors that work in light and dark mode and in high contrast. Tones are from the Agent Playgrounds catalog.

Shorthand ​

A few SDK components are shorthand that compile to plain A2UI:

SDKBecomes
A Card with several childrenA Card whose child is a Column
A Button with a string labelA Button whose child is a Text
onActionAn A2UI action event, routed back to your handler
FormA Column of fields bound to /form/…, plus a submit Button

So what you write stays short, and what's sent is always valid A2UI.

All your Agents, playing nicely in one Playground.