`)."
]
},
"composes_with": [
{
"component": "Avatar",
"relation": "child",
"note": "Leading slot."
},
{
"component": "IconButton",
"relation": "child",
"note": "Right-aligned actions."
},
{
"component": "ChatList",
"relation": "sibling",
"note": "Sits above the chat list."
},
{
"component": "ChatComposer",
"relation": "sibling"
}
],
"related": [
"ChatList",
"ChatComposer"
],
"when_to_use": [],
"pitfalls": [],
"prompt_examples": [
{
"intent": "one-on-one chat header",
"prompt": "header with avatar, name, online dot",
"snippet": "} title=\"Sara\" subtitle=\"online\" />\n"
}
]
},
{
"name": "ChatList",
"slug": "chat-list",
"package": "@helixui/core",
"import": "import { ChatList } from '@helixui/core'",
"description": "A scrolling container for ChatMessages with sticky-to-bottom auto-scroll. When the user has scrolled up to read history, new messages do NOT yank them back.",
"category": "chat",
"tags": [
"messages",
"scroll",
"sticky-bottom",
"feed"
],
"status": "stable",
"since": "0.3.0",
"layout": {
"display": "flex",
"width": "fill",
"height": "fill",
"intrinsicSize": "fills available height, scrolls",
"stackable": false,
"fullBleed": false
},
"anatomy": "┌────────────────────────┐\n│ [old messages above] │ ↑ scrolls\n│ ChatMessage │\n│ ChatMessage │\n│ ChatMessage ← new │ ← stays pinned to bottom unless user scrolled up\n└────────────────────────┘\n",
"visual": "A vertically scrolling column that auto-pins to the bottom when new messages arrive — but only if the user is already near the bottom. If they scrolled up to read history, new messages do not yank them back.\n",
"props": [
{
"name": "autoScroll",
"type": "boolean",
"default": true,
"description": "Auto-scroll on children change (only if user is near the bottom)."
},
{
"name": "label",
"type": "string",
"default": "Conversation",
"description": "`aria-label` for the log container."
}
],
"slots": [
"children — ChatMessage components"
],
"tokens": [
"space.4",
"font.family.sans"
],
"a11y": {
"role": "log",
"notes": [
"Container is `role=\"log\"` with `aria-live=\"polite\"`. New messages are announced once.",
"The sticky-to-bottom behaviour preserves the user's reading position when they scroll up."
]
},
"composes_with": [
{
"component": "ChatMessage",
"relation": "child",
"note": "Each child is a ChatMessage."
},
{
"component": "ChatHeader",
"relation": "sibling",
"note": "Sits below ChatHeader."
},
{
"component": "ChatComposer",
"relation": "sibling",
"note": "Sits above ChatComposer."
},
{
"component": "TypingIndicator",
"relation": "sibling"
}
],
"related": [
"ChatMessage",
"ChatComposer",
"TypingIndicator"
],
"when_to_use": [],
"pitfalls": [],
"prompt_examples": [
{
"intent": "render an AI conversation",
"prompt": "list of chat messages with sticky-bottom",
"snippet": "\n {messages.map(m => {m.content})}\n\n"
}
]
},
{
"name": "ChatMessage",
"slug": "chat-message",
"package": "@helixui/core",
"import": "import { ChatMessage } from '@helixui/core'",
"description": "A single message in a chat — user / assistant / system role, bubble or inline (Slack-style) variant, optional avatar / name / time / footer.",
"category": "chat",
"tags": [
"bubble",
"message",
"role",
"user",
"assistant"
],
"status": "stable",
"since": "0.3.0",
"layout": {
"display": "block",
"width": "fill",
"height": "content",
"intrinsicSize": "left or right aligned by role, max ~720px wide",
"stackable": true,
"fullBleed": false
},
"anatomy": "[avatar] Name · time\n ┌──────────────────────┐\n │ message body… │\n └──────────────────────┘\n [optional footer]\n",
"visual": "A row containing an avatar, a name + timestamp meta line, and a content bubble. User messages typically right-align with brand-tinted bubble; assistant left-aligns with neutral surface. The `inline` variant strips the bubble for Slack-style flat feeds.\n",
"props": [
{
"name": "role",
"type": "'user' | 'assistant' | 'system'",
"default": "assistant",
"description": "Speaker. `user` aligns right (in bubble variant); `system` centers and dims."
},
{
"name": "variant",
"type": "'bubble' | 'inline'",
"default": "bubble",
"description": "`bubble` for messenger UIs; `inline` for thread-style chat."
},
{
"name": "avatar",
"type": "ReactNode",
"default": "",
"description": "Avatar element rendered to the left (or right, for user)."
},
{
"name": "name",
"type": "ReactNode",
"default": "",
"description": "Display name. Position depends on variant."
},
{
"name": "time",
"type": "ReactNode",
"default": "",
"description": "Timestamp or relative time ('2m ago')."
},
{
"name": "pending",
"type": "boolean",
"default": false,
"description": "Mute the bubble while a message is being sent or streamed."
},
{
"name": "footer",
"type": "ReactNode",
"default": "",
"description": "Slot below the bubble — reactions, ToolCall, CitationList."
}
],
"slots": [
"children — message content (text, MarkdownMessage, CodeBlock, etc.)"
],
"tokens": [
"color.bg.action.brand.default",
"color.bg.action.neutral.default",
"color.text.primary",
"color.text.muted",
"color.text.on.brand",
"radius.lg",
"radius.sm",
"space.1",
"space.2",
"space.3",
"space.4",
"font.family.sans",
"font.size.xs",
"font.size.sm",
"font.weight.semibold"
],
"a11y": {
"notes": [
"The bubble itself is a styled `