Skip to content

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

TypeScript

feat(chat): add ChatMessageList align prop for top-aligned lists (#2572) (#3933)

Jiun Shin6759843deb0a
diff --git a/.changeset/chatmessagelist-add-align-prop-for-top-aligned-l-xm43.md b/.changeset/chatmessagelist-add-align-prop-for-top-aligned-l-xm43.md
new file mode 100644
index 0000000000..ebae48ff36
--- /dev/null
+++ b/.changeset/chatmessagelist-add-align-prop-for-top-aligned-l-xm43.md
@@ -0,0 +1,16 @@
+---
+'@astryxdesign/core': patch
+---
+
+[feat] ChatMessageList: add an `align` prop for top-aligned message lists
+(#2572).
+
+- `align?: 'top' | 'bottom'` (default `'bottom'`). `'bottom'` keeps the
+ existing behavior: a flex spacer fills free space so a short conversation
+ sits just above the composer. `'top'` omits the spacer so messages start at
+ the top and grow downward — better for log-style or document-style lists.
+- Only changes the resting position of a non-full list. Once messages overflow
+ the container the spacer collapses to zero in both modes, so ChatLayout
+ auto-scroll-to-bottom behavior is unchanged.
+
+@jiunshinn
diff --git a/apps/storybook/stories/Chat.stories.tsx b/apps/storybook/stories/Chat.stories.tsx
index 8db0d19b8e..b0b608ee50 100644
--- a/apps/storybook/stories/Chat.stories.tsx
+++ b/apps/storybook/stories/Chat.stories.tsx
@@ -591,3 +591,61 @@ export const MultiBubble: StoryObj = {
</div>
),
};
+export const Alignment: StoryObj = {
+ name: 'Alignment',
+ render: () => {
+ const shortConversation = (align: 'top' | 'bottom') => (
+ <div
+ style={{
+ flex: 1,
+ minWidth: 0,
+ display: 'flex',
+ flexDirection: 'column',
+ border: '1px solid var(--color-border-primary)',
+ borderRadius: 8,
+ overflow: 'hidden',
+ }}>
+ <div
+ style={{
+ padding: '8px 12px',
+ borderBottom: '1px solid var(--color-border-primary)',
+ fontSize: 12,
+ fontWeight: 600,
+ textTransform: 'uppercase',
+ letterSpacing: '0.05em',
+ }}>
+ align=&quot;{align}&quot;
+ </div>
+ <div
+ style={{
+ flex: 1,
+ display: 'flex',
+ flexDirection: 'column',
+ minHeight: 0,
+ }}>
+ <ChatMessageList align={align}>
+ <ChatMessage sender="user">
+ <ChatMessageBubble>Just one short message.</ChatMessageBubble>
+ </ChatMessage>
+ <ChatMessage
+ sender="assistant"
+ avatar={<Avatar name="Navi" size="small" />}>
+ <ChatMessageBubble>
+ {align === 'top'
+ ? 'Top alignment keeps messages at the top — good for logs and document-style lists.'
+ : 'Bottom alignment keeps a short thread just above the composer — the familiar messaging layout.'}
+ </ChatMessageBubble>
+ </ChatMessage>
+ </ChatMessageList>
+ </div>
+ </div>
+ );
+
+ return (
+ <div style={{display: 'flex', gap: 16, height: 420}}>
+ {shortConversation('bottom')}
+ {shortConversation('top')}
+ </div>
+ );
+ },
+};
diff --git a/packages/core/src/Chat/ChatMessageList.doc.mjs b/packages/core/src/Chat/ChatMessageList.doc.mjs
index 276eb95705..13f516dc9a 100644
--- a/packages/core/src/Chat/ChatMessageList.doc.mjs
+++ b/packages/core/src/Chat/ChatMessageList.doc.mjs
@@ -7,7 +7,7 @@ export const docs = {
subComponentOf: 'Chat',
displayName: 'Chat Message List',
isHiddenFromOverview: true,
- description: `Presentational message container with density context and infinite scroll support. Provides role="log" with aria-live="polite" for accessibility. A flex spacer pushes messages to the bottom when the list isn't full.`,
+ description: `Presentational message container with density context and infinite scroll support. Provides role="log" with aria-live="polite" for accessibility. A flex spacer pushes messages to the bottom when the list isn't full; set align="top" to start messages at the top instead.`,
props: [
{
name: 'children',
@@ -45,6 +45,12 @@ export const docs = {
type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10',
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: 'align',
+ type: "'top' | 'bottom'",
+ description: "Vertical alignment when the list is shorter than its container. 'bottom' fills free space with a spacer so short conversations sit above the composer; 'top' omits the spacer so messages start at the top. Only affects a non-full list; overflowing lists scroll identically, preserving auto-scroll-to-bottom.",
+ default: "'bottom'",
+ },
{
name: 'isStreaming',
type: 'boolean',
@@ -65,6 +71,7 @@ export const docsZh = {
scrollToTopAction: '用户滚动到顶部时触发的异步操作。用于加载更早的消息。',
density: '视觉密度,通过上下文传递给子消息。',
gap: '顶层消息行之间的间距。默认跟随密度;当 LLM 事件流等独立行需要不同间距时可覆盖。',
+ align: "列表内容不足一屏时的垂直对齐方式。'bottom' 用占位块填满剩余空间,让简短对话贴近输入框;'top' 省略占位块,让消息从顶部开始。仅影响未填满的列表,溢出后两种模式滚动一致,保持自动滚动到底部。",
isStreaming: '是否有助手消息正在流式输出。标记日志为 aria-busy,让屏幕阅读器等待并在完成后一次性播报,而不是每个 token 都重复播报。',
},
};
@@ -80,6 +87,7 @@ 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',
+ align: "'top'|'bottom' (def bottom); bottom spacer pushes short lists down, top starts at top; overflow scrolls same either way",
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 385303ea6c..1322757d2e 100644
--- a/packages/core/src/Chat/ChatMessageList.test.tsx
+++ b/packages/core/src/Chat/ChatMessageList.test.tsx
@@ -83,4 +83,50 @@ describe('ChatMessageList', () => {
);
expect(screen.getByTestId('chat-list')).toBeTruthy();
});
+
+ // With no scrollToTopAction the spacer is the only aria-hidden element in
+ // the list, so its presence maps 1:1 to the aria-hidden count.
+ it('renders the bottom spacer by default', () => {
+ render(
+ <ChatMessageList data-testid="list">
+ <div>msg</div>
+ </ChatMessageList>,
+ );
+ expect(
+ screen.getByTestId('list').querySelectorAll('[aria-hidden]'),
+ ).toHaveLength(1);
+ });
+
+ it('renders the bottom spacer when align="bottom"', () => {
+ render(
+ <ChatMessageList align="bottom" data-testid="list">
+ <div>msg</div>
+ </ChatMessageList>,
+ );
+ expect(
+ screen.getByTestId('list').querySelectorAll('[aria-hidden]'),
+ ).toHaveLength(1);
+ });
+
+ it('omits the spacer when align="top"', () => {
+ render(
+ <ChatMessageList align="top" data-testid="list">
+ <div>msg</div>
+ </ChatMessageList>,
+ );
+ expect(
+ screen.getByTestId('list').querySelectorAll('[aria-hidden]'),
+ ).toHaveLength(0);
+ });
+
+ it('still renders children when align="top"', () => {
+ render(
+ <ChatMessageList align="top">
+ <ChatMessage sender="assistant">
+ <ChatMessageBubble>Hello</ChatMessageBubble>
+ </ChatMessage>
+ </ChatMessageList>,
+ );
+ expect(screen.getByText('Hello')).toBeTruthy();
+ });
});
diff --git a/packages/core/src/Chat/ChatMessageList.tsx b/packages/core/src/Chat/ChatMessageList.tsx
index 6eca3d8f31..3f2468f4ce 100644
--- a/packages/core/src/Chat/ChatMessageList.tsx
+++ b/packages/core/src/Chat/ChatMessageList.tsx
@@ -10,7 +10,8 @@
*
* Renders a container with role="log" for chat message histories.
* Handles density context, configurable gap, empty state,
- * a spacer that pushes messages to the bottom, and an infinite scroll sentinel.
+ * a configurable spacer (align) that pushes messages to the bottom,
+ * and an infinite scroll sentinel.
*
* Auto-scroll and the scroll-to-bottom button are owned by
* ChatLayout. When used standalone (without a layout), the list
@@ -73,6 +74,24 @@ export interface ChatMessageListProps extends BaseProps<HTMLDivElement> {
*/
gap?: SpacingStep;
+ /**
+ * Vertical alignment of messages when the list is shorter than its
+ * container.
+ *
+ * - `'bottom'` (default): a spacer fills the free space and pushes
+ * messages to the bottom, so a short conversation sits just above the
+ * composer — the familiar messaging-app layout.
+ * - `'top'`: the spacer is omitted, so messages start at the top and grow
+ * downward — better for document-style or log-style lists.
+ *
+ * This only changes the resting position of a non-full list. Once messages
+ * overflow the container the spacer collapses to zero in both modes, so
+ * ChatLayout auto-scroll-to-bottom behavior is identical either way.
+ *
+ * @default 'bottom'
+ */
+ align?: 'top' | 'bottom';
+
/**
* Whether an assistant message is actively streaming into the list.
*
@@ -183,7 +202,8 @@ const gapStyles = stylex.create({
*
* Renders messages in a flex column with density-based spacing.
* Override gap to tune row spacing separately from density.
- * A spacer pushes content to the bottom when the list isn't full.
+ * By default a spacer pushes content to the bottom when the list isn't full;
+ * set `align='top'` to start messages at the top instead.
* Supports loading older messages via `scrollToTopAction`.
*
* Auto-scroll and the scroll-to-bottom button are owned by
@@ -204,6 +224,7 @@ export function ChatMessageList({
scrollToTopAction,
density = 'balanced',
gap,
+ align = 'bottom',
isStreaming = false,
xstyle,
className,
@@ -291,8 +312,11 @@ export function ChatMessageList({
</div>
)}
- {/* Spacer pushes messages to bottom when list isn't full */}
- <div {...stylex.props(styles.spacer)} aria-hidden />
+ {/* Spacer pushes messages to bottom when the list isn't full.
+ Omitted for top alignment so messages start at the top. */}
+ {align === 'bottom' && (
+ <div {...stylex.props(styles.spacer)} aria-hidden />
+ )}
{/* Messages or empty state */}
{hasChildren ? (