Appearance
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
MetricandTerminal, and optional props on some basic components, liketoneonText. 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
| Component | Catalog | Where | What it's for |
|---|---|---|---|
Card | Basic, with additions | Blocks, views | The main container for a block |
Column | Basic | Blocks, views | Arranges children top to bottom |
Row | Basic | Blocks, views | Arranges children side by side |
List | Basic | Blocks, views | A scrolling list of children, often ListItems |
Tabs | Basic | Views | Switches between titled panes |
Modal | Basic | Blocks, views | Opens content in a sheet when its trigger is used |
Divider | Basic | Blocks, views | A thin line between groups |
Card
tsx
<Card title="Lisbon" subtitle="Clear" icon={Icon.CloudSun} accessory={<Badge tone="success">Live</Badge>}>
…
</Card>| Prop | Catalog | Type | Description |
|---|---|---|---|
children | Basic | Components | The card's content. In A2UI a card has one child, so the SDK wraps several in a Column for you. |
title | Agent Playgrounds | string | The card's heading |
subtitle | Agent Playgrounds | string | A short line under the title |
icon | Agent Playgrounds | Icon | Shown beside the title |
accessory | Agent Playgrounds | Badge or Text | Shown at the trailing edge of the title row |
actions | Agent Playgrounds | Button elements | The first is shown on the card; the rest are in its … menu |
Column and Row
| Prop | Catalog | Type | Description |
|---|---|---|---|
justify | Basic | "start", "center", "end", "spaceBetween", "spaceAround", "spaceEvenly" or "stretch" | Distribution along the main axis |
align | Basic | "start", "center", "end" or "stretch" | Alignment across it |
Rows wrap onto more lines when there isn't room, such as on iPhone.
List
| Prop | Catalog | Type | Description |
|---|---|---|---|
direction | Basic | "vertical" (default) or "horizontal" | |
align | Basic | "start", "center", "end" or "stretch" | |
isLoading | Agent Playgrounds | boolean | Shows a loading state instead of an empty list |
searchable | Agent Playgrounds | boolean | Views only. Adds a search field that filters ListItems by title and keywords. |
pagination | Agent Playgrounds | { hasMore, onLoadMore } | Views only. Loads more as people scroll. |
Tabs, Modal and Divider
| Component | Props |
|---|---|
Tabs | tabs: { title, content }[] |
Modal | trigger: a component, usually a Button; content: what opens |
Divider | axis: "horizontal" (default) or "vertical" |
Content
| Component | Catalog | Where | What it's for |
|---|---|---|---|
Text | Basic, with additions | Blocks, views, slots | A heading, line or paragraph of plain text |
Image | Basic | Blocks, views | A picture from a URL |
Icon | Basic, with additions | Blocks, views, slots | A symbol |
Video | Basic | Blocks, views | A video from a URL |
AudioPlayer | Basic | Blocks, views | Audio from a URL |
Markdown | Agent Playgrounds | Blocks, views | Rich text: headings, lists, links, inline code |
Code | Agent Playgrounds | Blocks, views | Highlighted code with a copy button |
Badge | Agent Playgrounds | Blocks, views, slots | A short colored label, like "Merged" or "Stalled" |
Metric | Agent Playgrounds | Blocks, views | A big number with a label |
Progress | Agent Playgrounds | Blocks, views, slots | A progress bar, or a spinner when the amount is unknown |
Facts | Agent Playgrounds | Blocks, views | Label and value pairs, like a summary of a pull request |
ListItem | Agent Playgrounds | Blocks, views | A row with a title, icon and accessories |
Table | Agent Playgrounds | Blocks, views | Rows and columns of data |
Text
| Prop | Catalog | Type | Description |
|---|---|---|---|
children | Basic | string | The text. Sent as A2UI's text. |
variant | Basic | "h1" to "h5", "body" (default) or "caption" | |
tone | Agent Playgrounds | Tone | Defaults to "primary" |
lines | Agent Playgrounds | number | Truncates after this many lines |
Image
| Prop | Catalog | Type | Description |
|---|---|---|---|
url | Basic | string | An https URL your plugin may reach, or a file in assets/ |
description | Basic | string | Required by the SDK. Read aloud by VoiceOver and shown if the image can't load. |
fit | Basic | "contain", "cover", "fill", "none" or "scaleDown" | |
variant | Basic | "icon", "avatar", "smallFeature", "mediumFeature", "largeFeature" or "header" | Size and shape, chosen by the app to fit the context |
Icon
| Prop | Catalog | Type | Description |
|---|---|---|---|
name | Basic | Icon | An icon from the SDK's Icon list, which includes every basic catalog icon |
symbol | Agent Playgrounds | string | Any 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
| Component | Props |
|---|---|
Video | url |
AudioPlayer | url, description |
Markdown and Code
| Component | Props |
|---|---|
Markdown | children: CommonMark, with tables and task lists. Links go through the app's link policy. |
Code | children: the code; language: for highlighting, like "ts" |
Badge
| Prop | Type | Description |
|---|---|---|
children | string | One or two words |
tone | Tone | Defaults to "neutral" |
icon | Icon |
Metric
| Prop | Type | Description |
|---|---|---|
value | string | The number, already formatted, like "21°" or "1,204" |
label | string | What it measures |
trend | "up", "down" or "flat" | Shows an arrow next to the value |
tone | Tone |
Progress
| Prop | Type | Description |
|---|---|---|
value | number from 0 to 1 | Leave it out for an indeterminate spinner |
label | string | Like "Uploading" |
tone | Tone |
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>| Prop | Type | Description |
|---|---|---|
title | string | Required |
subtitle | string | |
icon | Icon | |
keywords | string[] | Extra words to match when searching |
accessories | Accessory[] | Shown at the trailing edge: { text }, { badge, tone } or { date }, shown relative, like "2h" |
actions | Button elements | The first runs when the row is clicked; the rest are in its context menu |
Table
| Prop | Type | Description |
|---|---|---|
columns | { key, title, align? }[] | |
rows | Record<string, string>[] |
Rich content
From the Agent Playgrounds catalog. Each can open into a larger surface.
| Component | Where | Props |
|---|---|---|
Terminal | Blocks, views | text, title, status: "running", "succeeded" or "failed". Follows the tail as output streams in. |
Map | Blocks, views | pins: { id, title, latitude, longitude }[], route: [latitude, longitude][], title |
WebPage | Blocks, views | url, title. A link card that opens in a safe browser. |
Diff | Blocks, views | Changes 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>| Prop | Catalog | Type | Description |
|---|---|---|---|
children | Basic | string or components | The label. A string becomes a Text child. |
variant | Basic | "default", "primary" or "borderless" | |
onAction | Basic | (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. |
action | Basic | A function call | Runs in the app without a round trip: openUrl(url), copyToClipboard(text) or openSurface(name, props) |
checks | Basic | Check functions | Disables the button until every check passes, like [required('/form/title')] |
icon | Agent Playgrounds | Icon | Shown before the label |
destructive | Agent Playgrounds | boolean | Shown in red, and asks for confirmation first |
shortcut | Agent Playgrounds | Shortcut | A 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>| Component | Catalog | What it's for |
|---|---|---|
TextField | Basic | Text. variant: "shortText" (default), "longText", "number" or "obscured" |
CheckBox | Basic | On or off |
ChoicePicker | Basic | One choice, or several with variant="multipleSelection". displayStyle: "checkbox" or "chips". |
DateTimeInput | Basic | A date, a time, or both, with min and max |
Slider | Basic | A 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:
| SDK | Becomes |
|---|---|
A Card with several children | A Card whose child is a Column |
A Button with a string label | A Button whose child is a Text |
onAction | An A2UI action event, routed back to your handler |
Form | A Column of fields bound to /form/…, plus a submit Button |
So what you write stays short, and what's sent is always valid A2UI.