diff --git a/apps/website/content/docs/react/chat/a2ui/surface-component.mdx b/apps/website/content/docs/react/chat/a2ui/surface-component.mdx
index 7af284cee..e3c37b0e6 100644
--- a/apps/website/content/docs/react/chat/a2ui/surface-component.mdx
+++ b/apps/website/content/docs/react/chat/a2ui/surface-component.mdx
@@ -117,6 +117,9 @@ The `context` is read from the data model at the moment of the press, so it carr
When the agent created the surface with `sendDataModel: true`, the whole data model rides along as `metadata.a2uiClientDataModel`.
How the message reaches the agent is your decision (most applications send it as the next turn of the conversation).
+When you send it as a user message, `Chat` and `MessageList` show the button's label, such as "Search flights", in place of the serialized message.
+An action from a control without literal text shows its name in plain words, so `bookingSubmit` reads "Booking submit".
+Pass `a2uiActionLabels={false}` to show the message as it was sent.
Without `onAction`, buttons that would send an action are disabled, so a read-only surface cannot look pressable.
## What happens when a check fails?
diff --git a/libs/react/README.md b/libs/react/README.md
index b12ea107b..55af958b7 100644
--- a/libs/react/README.md
+++ b/libs/react/README.md
@@ -2151,6 +2151,17 @@ retries and what the conversation shows are your application's decisions.
`createA2uiActionMessage(surface, componentId)` from
`@threadplane/content/a2ui` builds the same message outside React.
+When an application sends the message as the next user turn, `Chat` and
+`MessageList` do not show its JSON. A user message that is a serialized action
+shows the `label` instead ("Search flights"), or the action name in plain
+words when there is none (`bookingSubmit` reads "Booking submit"). The stored
+message is unchanged, and every other message renders as before. Pass
+`a2uiActionLabels={false}` to show the message as sent.
+
+```tsx
+
+```
+
A Button with an event action is disabled when there is no `onAction`. A
Button with no action, or whose `disabled` prop is true, is disabled too. A
Button used as a `Modal` trigger opens the modal and needs no action.
diff --git a/libs/react/src/chat/chat.tsx b/libs/react/src/chat/chat.tsx
index 46a9fe400..d003b6927 100644
--- a/libs/react/src/chat/chat.tsx
+++ b/libs/react/src/chat/chat.tsx
@@ -111,6 +111,8 @@ export interface ChatProps
readonly renderMessageActivity?: MessageListProps['renderMessageActivity'];
/** One reasoning disclosure per multi-step turn; see `MessageListProps.mergeReasoning`. Defaults to true. */
readonly mergeReasoning?: MessageListProps['mergeReasoning'];
+ /** Shows an A2UI action sent as a user message by its label; see `MessageListProps.a2uiActionLabels`. Defaults to true. */
+ readonly a2uiActionLabels?: MessageListProps['a2uiActionLabels'];
/**
* The waiting indicator in the transcript; see `MessageListProps.typingIndicator`. Pass
* `{ announce: false }` when the app already announces progress, such as a status in
@@ -223,6 +225,7 @@ export function Chat({
generativeUi,
markdownComponents,
mergeReasoning,
+ a2uiActionLabels,
renderMessageActivity,
typingIndicator,
welcome,
@@ -404,6 +407,7 @@ export function Chat({
generativeUi={generativeUi}
markdownComponents={markdownComponents}
mergeReasoning={mergeReasoning}
+ a2uiActionLabels={a2uiActionLabels}
renderMessageActivity={renderMessageActivity}
typingIndicator={typingIndicator}
renderScrollControl={(controls) =>
diff --git a/libs/react/src/chat/chat.type-test.tsx b/libs/react/src/chat/chat.type-test.tsx
index d9ee94be4..105033e2c 100644
--- a/libs/react/src/chat/chat.type-test.tsx
+++ b/libs/react/src/chat/chat.type-test.tsx
@@ -71,6 +71,9 @@ ok.className = 'x';
;
// @ts-expect-error Options are value and label records, not strings.
undefined }} />;
+;
+// @ts-expect-error Action labels are a switch, not a renderer.
+ 'Go'} />;
void missing;
import type { ReactNode } from 'react';
diff --git a/libs/react/src/chat/internal/a2ui-action-label.ts b/libs/react/src/chat/internal/a2ui-action-label.ts
new file mode 100644
index 000000000..c825c485b
--- /dev/null
+++ b/libs/react/src/chat/internal/a2ui-action-label.ts
@@ -0,0 +1,30 @@
+const record = (value: unknown): value is Record =>
+ value != null && typeof value === 'object' && !Array.isArray(value);
+
+/**
+ * The words to show for a message whose content is a serialized A2UI action
+ * (`{"version":"v0.9","action":{…}}`): the pressed control's own label, or the
+ * action name in plain words ("bookingSubmit" reads "Booking submit"). Null
+ * for any other content.
+ */
+export function a2uiActionLabel(content: string): string | null {
+ const trimmed = content.trimStart();
+ if (!trimmed.startsWith('{')) return null;
+ let parsed: unknown;
+ try {
+ parsed = JSON.parse(trimmed);
+ } catch {
+ return null;
+ }
+ if (!record(parsed)) return null;
+ const version = parsed['version'];
+ if (typeof version !== 'string' || !version.startsWith('v')) return null;
+ const action = parsed['action'];
+ if (!record(action)) return null;
+ const name = action['name'];
+ if (typeof name !== 'string' || name === '') return null;
+ const label = action['label'];
+ if (typeof label === 'string' && label !== '') return label;
+ const words = name.replace(/([a-z])([A-Z])/g, '$1 $2').toLowerCase();
+ return words.charAt(0).toUpperCase() + words.slice(1);
+}
diff --git a/libs/react/src/chat/message-list-a2ui-action-label.spec.tsx b/libs/react/src/chat/message-list-a2ui-action-label.spec.tsx
new file mode 100644
index 000000000..fbd7a9f10
--- /dev/null
+++ b/libs/react/src/chat/message-list-a2ui-action-label.spec.tsx
@@ -0,0 +1,151 @@
+import { cleanup, render } from '@testing-library/react';
+import { afterEach, describe, expect, it } from 'vitest';
+import {
+ completeDelivery,
+ type AgentSession,
+ type AgentSnapshot,
+ type Message,
+} from '@threadplane/core';
+import { createA2uiActionMessage } from '@threadplane/content/a2ui';
+import { createMessageContent } from '@threadplane/content/messages';
+import { Chat, MessageList } from './index';
+
+afterEach(cleanup);
+
+const msg = (id: string, role: Message['role'], content: string): Message =>
+ Object.freeze({ id, role, content, delivery: completeDelivery(id, 'success') }) as Message;
+const snapshot = (messages: Message[]) =>
+ Object.freeze({ status: 'idle', messages, toolCalls: [] }) as AgentSnapshot;
+const project = (messages: Message[]) => createMessageContent().project(snapshot(messages));
+const action = (fields: Record) =>
+ JSON.stringify({ version: 'v0.9', action: { surfaceId: 's', sourceComponentId: 'b', context: {}, ...fields } });
+const bubble = (view: ReturnType) =>
+ view.container.querySelector('.tp-chat-message--user');
+// The message text alone, without the row's screen-reader role prefix.
+const text = (view: ReturnType) =>
+ view.container.querySelector('.tp-chat-message--user .tp-markdown')?.textContent;
+
+describe('MessageList A2UI action labels', () => {
+ it('leaves the serialized action in place when turned off', () => {
+ const view = render(
+
+ );
+ expect(bubble(view)?.textContent).toContain('"bookingSubmit"');
+ expect(view.container.querySelector('[data-a2ui-action]')).toBeNull();
+ });
+
+ it('shows the pressed control label in place of the JSON by default', () => {
+ const view = render(
+
+ );
+ expect(text(view)).toBe('Search flights');
+ expect(bubble(view)?.querySelector('.tp-markdown[data-a2ui-action] > p')).not.toBeNull();
+ });
+
+ it('labels the message the shared builder produces for a Button', () => {
+ const message = createA2uiActionMessage(
+ {
+ surfaceId: 's',
+ components: [
+ { id: 'go', component: 'Button', child: 'go-text', action: { event: { name: 'bookingSubmit' } } },
+ { id: 'go-text', component: 'Text', text: 'Search flights' },
+ ],
+ dataModel: {},
+ } as never,
+ 'go',
+ '2026-11-17T00:00:00.000Z'
+ );
+ const view = render(
+
+ );
+ expect(text(view)).toBe('Search flights');
+ });
+
+ it('puts the action name in plain words when no label was sent', () => {
+ for (const [name, words] of [
+ ['bookingSubmit', 'Booking submit'],
+ ['addToCart', 'Add to cart'],
+ ['refresh', 'Refresh'],
+ ]) {
+ const view = render(
+
+ );
+ expect(text(view)).toBe(words);
+ cleanup();
+ }
+ });
+
+ it('leaves every other user message as written', () => {
+ for (const content of [
+ 'Find me a flight',
+ '{"city":"Paris"}',
+ '{not json',
+ '{"version":"v0.9"}',
+ '{"version":"v0.9","action":{"label":"No name"}}',
+ '{"version":1,"action":{"name":"go"}}',
+ '[{"version":"v0.9","action":{"name":"go"}}]',
+ ]) {
+ const plain = render();
+ const expected = bubble(plain)?.innerHTML;
+ cleanup();
+ const view = render();
+ expect(bubble(view)?.innerHTML).toBe(expected);
+ cleanup();
+ }
+ });
+
+ it('never relabels an assistant message that quotes an action', () => {
+ const content = action({ name: 'bookingSubmit', label: 'Search flights' });
+ const view = render();
+ const row = view.container.querySelector('.tp-chat-message--assistant');
+ expect(row?.textContent).toContain('"bookingSubmit"');
+ expect(row?.querySelector('[data-a2ui-action]')).toBeNull();
+ });
+
+ it('renders the label as text, not markup', () => {
+ const view = render(
+ ' }))])}
+ />
+ );
+ expect(text(view)).toBe('**Bold**
');
+ expect(bubble(view)?.querySelector('img, strong')).toBeNull();
+ });
+
+ it('leaves a custom renderMessage in charge of the row', () => {
+ const view = render(
+ {row.message.content.length}}
+ rows={project([msg('u', 'user', action({ name: 'go', label: 'Go' }))])}
+ />
+ );
+ expect(view.container.querySelector('[data-custom]')).not.toBeNull();
+ expect(view.container.querySelector('[data-a2ui-action]')).toBeNull();
+ });
+});
+
+describe('Chat A2UI action labels', () => {
+ const session = (messages: Message[]): AgentSession => {
+ const value = snapshot(messages);
+ return {
+ getSnapshot: () => value,
+ subscribe: () => () => undefined,
+ submit: async () => undefined,
+ stop: async () => undefined,
+ } as unknown as AgentSession;
+ };
+ const messages = [msg('u', 'user', action({ name: 'bookingSubmit', label: 'Search flights' }))];
+
+ it('passes the choice through to its transcript', () => {
+ const off = render();
+ expect(bubble(off)?.textContent).toContain('"bookingSubmit"');
+ cleanup();
+ const on = render();
+ expect(text(on)).toBe('Search flights');
+ });
+});
diff --git a/libs/react/src/chat/message-list.tsx b/libs/react/src/chat/message-list.tsx
index 2b3091ed0..73585bcd2 100644
--- a/libs/react/src/chat/message-list.tsx
+++ b/libs/react/src/chat/message-list.tsx
@@ -26,6 +26,7 @@ import {
withoutStaleRetry,
} from './tool-outcome.js';
import { Reasoning } from './reasoning.js';
+import { a2uiActionLabel } from './internal/a2ui-action-label.js';
import { isTyping, TypingIndicator } from './typing-indicator.js';
import {
BuiltInActions,
@@ -190,6 +191,14 @@ export interface MessageListProps {
* reasoning on its own message. Custom renderMessage retains full row ownership.
*/
readonly mergeReasoning?: boolean;
+ /**
+ * Shows a user message that is a serialized A2UI action as the pressed
+ * control's label ("Search flights") in place of its JSON. Without a label
+ * the action name is put in plain words. Defaults to true; false shows the
+ * JSON as sent. Other messages are unchanged, and custom renderMessage
+ * retains full row ownership.
+ */
+ readonly a2uiActionLabels?: boolean;
/** Typesets math in message text; see `MarkdownProps.math`. Keep stable; custom renderMessage retains full ownership. */
readonly math?: MarkdownProps['math'];
/**
@@ -393,8 +402,10 @@ function RowView({
generativeUi,
markdownComponents,
mergeReasoning,
+ a2uiActionLabels,
renderMessageActivity,
}: {
+ readonly a2uiActionLabels?: boolean;
readonly renderMessageActivity?: (
context: MessageActivityContext
) => ReactNode;
@@ -525,14 +536,23 @@ function RowView({
});
// The plan and Stop belong to the row's last built-in group, the one the turn is still running.
const planGroup = [...runs].reverse().find((run) => 'activities' in run);
- const text = (
-
- );
+ const actionLabel =
+ a2uiActionLabels !== false && row.role === 'user'
+ ? a2uiActionLabel(row.message.content)
+ : null;
+ const text =
+ actionLabel !== null ? (
+
+ ) : (
+
+ );
return (
({
generativeUi,
markdownComponents,
mergeReasoning,
+ a2uiActionLabels,
renderMessageActivity,
children,
renderScrollControl,
@@ -851,6 +872,7 @@ export function MessageList({
generativeUi={generativeUi}
markdownComponents={markdownComponents}
mergeReasoning={mergeReasoning !== false}
+ a2uiActionLabels={a2uiActionLabels}
renderMessageActivity={renderMessageActivity}
/>
{renderApprovalRecords(recordsAfter, row.id)}
diff --git a/scripts/react-parity/dispositions.json b/scripts/react-parity/dispositions.json
index e1f6dc073..55914508a 100644
--- a/scripts/react-parity/dispositions.json
+++ b/scripts/react-parity/dispositions.json
@@ -15017,6 +15017,17 @@
"reason": "Internal hook projecting snapshots through app-passed message content, or owning one projection per session for Chat; not exported.",
"note": "Verified through the Chat DOM tests: owned disposal on unmount and session change, StrictMode recreation, and app-passed content never disposed. Not part of the public surface."
},
+ {
+ "id": "source:libs/react/src/chat/internal/a2ui-action-label.ts",
+ "taskIds": [
+ "T22",
+ "T27"
+ ],
+ "treatment": "react",
+ "status": "in-progress",
+ "reason": "Internal reader giving the words for a user message that is a serialized A2UI action: its stamped label, or the action name in plain words; not exported.",
+ "note": "Verified through the MessageList and Chat DOM tests: default label, opt-out, name fallback, untouched non-action and assistant messages, and text-only rendering. Not part of the public surface."
+ },
{
"id": "source:libs/react/src/chat/message-list.tsx",
"taskIds": [