Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

fix(chat): aria-busy on the log while streaming (complex-5) (#3393)

Cindy Zhange85eff33c275
diff --git a/.changeset/chat-streaming-aria-busy.md b/.changeset/chat-streaming-aria-busy.md
new file mode 100644
index 0000000000..5b7054ef84
--- /dev/null
+++ b/.changeset/chat-streaming-aria-busy.md
@@ -0,0 +1,6 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] ChatMessageList: add an `isStreaming` prop that marks the `role="log"` region `aria-busy` while an assistant message streams in. Previously the polite live region re-announced the accumulating partial text on every token; with `isStreaming` set for the duration of a stream, screen readers wait and announce the completed message once (#3343).
+@cixzhang
diff --git a/packages/core/src/Chat/ChatMessageList.doc.mjs b/packages/core/src/Chat/ChatMessageList.doc.mjs
index 09385f5841..8cbb18e229 100644
--- a/packages/core/src/Chat/ChatMessageList.doc.mjs
+++ b/packages/core/src/Chat/ChatMessageList.doc.mjs
@@ -45,6 +45,12 @@ export const docs = {
type: 'SpacingStep',
description: 'Gap between top-level message rows. Defaults to the selected density; override for LLM event streams or independent rows that need different spacing from density.',
},
+ {
+ name: 'isStreaming',
+ type: 'boolean',
+ description: 'Whether an assistant message is actively streaming. Marks the log aria-busy so screen readers wait and announce the completed message once instead of re-announcing partial text on every token.',
+ default: 'false',
+ },
],
};
@@ -59,6 +65,7 @@ export const docsZh = {
scrollToTopAction: '用户滚动到顶部时触发的异步操作。用于加载更早的消息。',
density: '视觉密度,通过上下文传递给子消息。',
gap: '顶层消息行之间的间距。默认跟随密度;当 LLM 事件流等独立行需要不同间距时可覆盖。',
+ isStreaming: '是否有助手消息正在流式输出。标记日志为 aria-busy,让屏幕阅读器等待并在完成后一次性播报,而不是每个 token 都重复播报。',
},
};
@@ -73,5 +80,6 @@ export const docsDense = {
scrollToTopAction: 'async action at scroll top; load older msgs',
density: 'visual density; flows to children via context',
gap: 'top-level row gap; defaults to density spacing; override for independent LLM/tool rows',
+ isStreaming: 'assistant streaming? marks log aria-busy so SR announces the completed msg once',
},
};
diff --git a/packages/core/src/Chat/ChatMessageList.test.tsx b/packages/core/src/Chat/ChatMessageList.test.tsx
index 44e8bd04d8..385303ea6c 100644
--- a/packages/core/src/Chat/ChatMessageList.test.tsx
+++ b/packages/core/src/Chat/ChatMessageList.test.tsx
@@ -28,6 +28,24 @@ describe('ChatMessageList', () => {
expect(el.getAttribute('role')).toBe('log');
});
+ it('is not aria-busy by default', () => {
+ render(
+ <ChatMessageList data-testid="list">
+ <div>msg</div>
+ </ChatMessageList>,
+ );
+ expect(screen.getByTestId('list')).not.toHaveAttribute('aria-busy');
+ });
+
+ it('marks the log aria-busy while streaming', () => {
+ render(
+ <ChatMessageList data-testid="list" isStreaming>
+ <div>msg</div>
+ </ChatMessageList>,
+ );
+ expect(screen.getByTestId('list')).toHaveAttribute('aria-busy', 'true');
+ });
+
it('renders empty state when no children', () => {
render(
<ChatMessageList emptyState={<div>No messages yet</div>}>
diff --git a/packages/core/src/Chat/ChatMessageList.tsx b/packages/core/src/Chat/ChatMessageList.tsx
index 7ba5ff2f99..6c50bfda2e 100644
--- a/packages/core/src/Chat/ChatMessageList.tsx
+++ b/packages/core/src/Chat/ChatMessageList.tsx
@@ -72,6 +72,20 @@ export interface ChatMessageListProps extends BaseProps<HTMLDivElement> {
* be grouped) and row spacing should be tuned separately from density.
*/
gap?: SpacingStep;
+
+ /**
+ * Whether an assistant message is actively streaming into the list.
+ *
+ * The list is a `role="log"` / `aria-live="polite"` region, so while a
+ * message streams in token-by-token, screen readers would otherwise
+ * re-announce the accumulating partial text on every mutation. Set
+ * `isStreaming` to `true` for the duration of a stream: it marks the log
+ * `aria-busy="true"` so assistive tech waits and announces the completed
+ * message once, when `isStreaming` returns to `false`.
+ *
+ * @default false
+ */
+ isStreaming?: boolean;
}
// =============================================================================
@@ -190,6 +204,7 @@ export function ChatMessageList({
scrollToTopAction,
density = 'balanced',
gap,
+ isStreaming = false,
xstyle,
className,
style,
@@ -252,6 +267,7 @@ export function ChatMessageList({
ref={ref}
role="log"
aria-live="polite"
+ aria-busy={isStreaming || undefined}
tabIndex={0}
data-testid={testId}
{...mergeProps(