Skip to content

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

TypeScript

docs: improve ChatSendButton usage docs and block examples (#1864)

Kenton Quatman941889a4911e
diff --git a/packages/cli/templates/blocks/components/ChatSendButton/ChatSendButtonCustomIcon.doc.mjs b/packages/cli/templates/blocks/components/ChatSendButton/ChatSendButtonCustomIcon.doc.mjs
new file mode 100644
index 0000000000..3d2a91dd23
--- /dev/null
+++ b/packages/cli/templates/blocks/components/ChatSendButton/ChatSendButtonCustomIcon.doc.mjs
@@ -0,0 +1,9 @@
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ name: 'ChatSendButton — Custom Icon',
+ description: 'Send buttons with custom icons via sendIcon and stopIcon props. Use to match the personality of the chat experience — a paper airplane for messaging, sparkles for AI generation, or a check mark for confirmation flows.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['Chat', 'ChatSendButton', 'Icon', 'Layout', 'Text'],
+};
diff --git a/packages/cli/templates/blocks/components/ChatSendButton/ChatSendButtonCustomIcon.tsx b/packages/cli/templates/blocks/components/ChatSendButton/ChatSendButtonCustomIcon.tsx
new file mode 100644
index 0000000000..1258da0927
--- /dev/null
+++ b/packages/cli/templates/blocks/components/ChatSendButton/ChatSendButtonCustomIcon.tsx
@@ -0,0 +1,44 @@
+'use client';
+
+import {XDSChatSendButton} from '@xds/core/Chat';
+import {XDSIcon} from '@xds/core/Icon';
+import {XDSStack} from '@xds/core/Layout';
+import {XDSText} from '@xds/core/Text';
+import {
+ CheckIcon,
+ PaperAirplaneIcon,
+ SparklesIcon,
+} from '@heroicons/react/24/solid';
+import {XCircleIcon} from '@heroicons/react/24/outline';
+
+export default function ChatSendButtonCustomIcon() {
+ return (
+ <XDSStack direction="vertical" gap={4}>
+ <XDSText type="supporting" color="secondary">
+ Custom icons for send and stop states
+ </XDSText>
+ <XDSStack direction="horizontal" gap={4} vAlign="center">
+ <XDSChatSendButton
+ isDisabled={false}
+ onSend={() => {}}
+ sendIcon={<XDSIcon icon={PaperAirplaneIcon} size="sm" />}
+ />
+ <XDSChatSendButton
+ isDisabled={false}
+ onSend={() => {}}
+ sendIcon={<XDSIcon icon={CheckIcon} size="sm" />}
+ />
+ <XDSChatSendButton
+ isDisabled={false}
+ onSend={() => {}}
+ sendIcon={<XDSIcon icon={SparklesIcon} size="sm" />}
+ />
+ <XDSChatSendButton
+ isStreaming
+ onStop={() => {}}
+ stopIcon={<XDSIcon icon={XCircleIcon} size="sm" />}
+ />
+ </XDSStack>
+ </XDSStack>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/ChatSendButton/ChatSendButtonInComposer.doc.mjs b/packages/cli/templates/blocks/components/ChatSendButton/ChatSendButtonInComposer.doc.mjs
new file mode 100644
index 0000000000..02962b980c
--- /dev/null
+++ b/packages/cli/templates/blocks/components/ChatSendButton/ChatSendButtonInComposer.doc.mjs
@@ -0,0 +1,9 @@
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ name: 'ChatSendButton — In Composer',
+ description: 'Send button inside XDSChatComposer, where it reads state from context automatically. No wiring needed — the button enables when the input has content.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['Chat', 'ChatComposer', 'ChatSendButton', 'Layout'],
+};
diff --git a/packages/cli/templates/blocks/components/ChatSendButton/ChatSendButtonInComposer.tsx b/packages/cli/templates/blocks/components/ChatSendButton/ChatSendButtonInComposer.tsx
new file mode 100644
index 0000000000..659eb24a42
--- /dev/null
+++ b/packages/cli/templates/blocks/components/ChatSendButton/ChatSendButtonInComposer.tsx
@@ -0,0 +1,23 @@
+'use client';
+
+import * as stylex from '@stylexjs/stylex';
+import {XDSChatComposer} from '@xds/core/Chat';
+import {XDSStack} from '@xds/core/Layout';
+
+const styles = stylex.create({
+ root: {
+ maxWidth: 450,
+ },
+});
+
+export default function ChatSendButtonInComposer() {
+ return (
+ <XDSStack direction="vertical" width="100%" xstyle={styles.root}>
+ <XDSChatComposer
+ onSubmit={() => {}}
+ value="Hello, how can you help?"
+ onChange={() => {}}
+ />
+ </XDSStack>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/ChatSendButton/ChatSendButtonShowcase.doc.mjs b/packages/cli/templates/blocks/components/ChatSendButton/ChatSendButtonShowcase.doc.mjs
index 6213bf49a6..abe925267d 100644
--- a/packages/cli/templates/blocks/components/ChatSendButton/ChatSendButtonShowcase.doc.mjs
+++ b/packages/cli/templates/blocks/components/ChatSendButton/ChatSendButtonShowcase.doc.mjs
@@ -2,9 +2,9 @@
export const doc = {
type: 'block',
name: 'ChatSendButton',
- description: 'Send button in default, active, streaming, custom icon, small size, and standalone states.',
+ description: 'Ready, custom icon, and streaming states of the send button.',
isReady: true,
isShowcase: true,
aspectRatio: 16 / 9,
- componentsUsed: ['Chat', 'ChatSendButton', 'Icon', 'Layout', 'Text'],
+ componentsUsed: ['Chat', 'ChatSendButton', 'Icon', 'Layout'],
};
diff --git a/packages/cli/templates/blocks/components/ChatSendButton/ChatSendButtonShowcase.tsx b/packages/cli/templates/blocks/components/ChatSendButton/ChatSendButtonShowcase.tsx
index 3c7463afc3..8a91836dc8 100644
--- a/packages/cli/templates/blocks/components/ChatSendButton/ChatSendButtonShowcase.tsx
+++ b/packages/cli/templates/blocks/components/ChatSendButton/ChatSendButtonShowcase.tsx
@@ -1,103 +1,20 @@
'use client';
-import {XDSChatComposer, XDSChatSendButton} from '@xds/core/Chat';
+import {XDSChatSendButton} from '@xds/core/Chat';
import {XDSIcon} from '@xds/core/Icon';
import {XDSStack} from '@xds/core/Layout';
-import {XDSText} from '@xds/core/Text';
+import {SparklesIcon} from '@heroicons/react/24/solid';
export default function ChatSendButtonShowcase() {
return (
- <XDSStack direction="vertical" gap={4}>
- <XDSStack direction="vertical" gap={1}>
- <XDSText type="supporting" color="secondary">
- Default (empty input — disabled)
- </XDSText>
- <XDSChatComposer onSubmit={() => {}} />
- </XDSStack>
-
- <XDSStack direction="vertical" gap={1}>
- <XDSText type="supporting" color="secondary">
- With content (enabled)
- </XDSText>
- <XDSChatComposer
- onSubmit={() => {}}
- value="Ready to send"
- onChange={() => {}}
- />
- </XDSStack>
-
- <XDSStack direction="vertical" gap={1}>
- <XDSText type="supporting" color="secondary">
- Streaming (shows stop button)
- </XDSText>
- <XDSChatComposer
- onSubmit={() => {}}
- onStop={() => {}}
- isStreaming
- />
- </XDSStack>
-
- <XDSStack direction="vertical" gap={1}>
- <XDSText type="supporting" color="secondary">
- Custom send icon
- </XDSText>
- <XDSChatComposer
- onSubmit={() => {}}
- value="Custom icon"
- onChange={() => {}}
- sendButton={
- <XDSChatSendButton
- sendIcon={<XDSIcon icon="check" size="sm" />}
- onSend={() => {}}
- isDisabled={false}
- />
- }
- />
- </XDSStack>
-
- <XDSStack direction="vertical" gap={1}>
- <XDSText type="supporting" color="secondary">
- Small size
- </XDSText>
- <XDSChatComposer
- onSubmit={() => {}}
- value="Small send button"
- onChange={() => {}}
- density="compact"
- sendButton={
- <XDSChatSendButton
- size="sm"
- onSend={() => {}}
- isDisabled={false}
- />
- }
- />
- </XDSStack>
-
- <XDSStack direction="vertical" gap={1}>
- <XDSText type="supporting" color="secondary">
- Standalone (outside composer context)
- </XDSText>
- <XDSStack direction="horizontal" gap={2} vAlign="center">
- <XDSChatSendButton
- isDisabled={true}
- onSend={() => {}}
- />
- <XDSChatSendButton
- isDisabled={false}
- onSend={() => {}}
- />
- <XDSChatSendButton
- isStreaming={true}
- onStop={() => {}}
- />
- <XDSChatSendButton
- size="sm"
- isDisabled={false}
- onSend={() => {}}
- />
- </XDSStack>
- </XDSStack>
+ <XDSStack direction="horizontal" gap={3} vAlign="center">
+ <XDSChatSendButton isDisabled={false} onSend={() => {}} />
+ <XDSChatSendButton
+ isDisabled={false}
+ onSend={() => {}}
+ sendIcon={<XDSIcon icon={SparklesIcon} size="sm" />}
+ />
+ <XDSChatSendButton isStreaming onStop={() => {}} />
</XDSStack>
);
}
diff --git a/packages/cli/templates/blocks/components/ChatSendButton/ChatSendButtonStates.doc.mjs b/packages/cli/templates/blocks/components/ChatSendButton/ChatSendButtonStates.doc.mjs
new file mode 100644
index 0000000000..bf0b082eb9
--- /dev/null
+++ b/packages/cli/templates/blocks/components/ChatSendButton/ChatSendButtonStates.doc.mjs
@@ -0,0 +1,9 @@
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ name: 'ChatSendButton — States',
+ description: 'Disabled, ready, and streaming states at both sizes. The button automatically toggles between send (primary) and stop (secondary) based on streaming state.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['Chat', 'ChatSendButton', 'Layout', 'Text'],
+};
diff --git a/packages/cli/templates/blocks/components/ChatSendButton/ChatSendButtonStates.tsx b/packages/cli/templates/blocks/components/ChatSendButton/ChatSendButtonStates.tsx
new file mode 100644
index 0000000000..4e11893333
--- /dev/null
+++ b/packages/cli/templates/blocks/components/ChatSendButton/ChatSendButtonStates.tsx
@@ -0,0 +1,20 @@
+'use client';
+
+import {XDSChatSendButton} from '@xds/core/Chat';
+import {XDSStack} from '@xds/core/Layout';
+import {XDSText} from '@xds/core/Text';
+
+export default function ChatSendButtonStates() {
+ return (
+ <XDSStack direction="vertical" gap={2}>
+ <XDSText type="supporting" color="secondary">
+ Disabled → Ready → Streaming
+ </XDSText>
+ <XDSStack direction="horizontal" gap={3} vAlign="center">
+ <XDSChatSendButton isDisabled onSend={() => {}} />
+ <XDSChatSendButton isDisabled={false} onSend={() => {}} />
+ <XDSChatSendButton isStreaming onStop={() => {}} />
+ </XDSStack>
+ </XDSStack>
+ );
+}
diff --git a/packages/core/src/Chat/Chat.doc.mjs b/packages/core/src/Chat/Chat.doc.mjs
index 181cf551e4..314a1fe802 100644
--- a/packages/core/src/Chat/Chat.doc.mjs
+++ b/packages/core/src/Chat/Chat.doc.mjs
@@ -138,7 +138,7 @@ export const docs = {
},
{
name: 'XDSChatSendButton',
- description: 'Circular send/stop toggle button for the composer. Reads state from XDSChatComposerContext by default so it works automatically inside XDSChatComposer. All context values can be overridden via props for standalone usage.',
+ description: 'Circular send/stop toggle button for the chat composer. Place it inside XDSChatComposer where it reads context automatically — no wiring needed. When streaming starts, the button switches from a primary send icon to a secondary stop icon. Override any context value via props for standalone or custom usage.',
props: [
{name: 'isStreaming', type: 'boolean', description: 'Whether the assistant is currently streaming. Defaults to context value.'},
{name: 'isDisabled', type: 'boolean', description: 'Whether the send button is disabled. Defaults to !canSend from context.'},
@@ -212,6 +212,9 @@ export const docs = {
{ guidance: false, description: 'Don\'t apply a fixed height directly on XDSChatLayout — wrap it in a sized container and let the layout fill with flex: 1.' },
{ guidance: true, description: 'Show a label on XDSChatLayoutScrollButton (e.g. "New messages") when unread content arrives below the fold so the user knows there is something to see.' },
{ guidance: false, description: 'Don\'t rebuild the scroll-to-bottom button from scratch — use XDSChatLayoutScrollButton or pass a custom element to XDSChatLayout\'s scrollButton prop.' },
+ { guidance: true, description: 'Let XDSChatSendButton read state from XDSChatComposerContext by default — it handles disabled, send, and stop states automatically. Only override via props when using the button standalone or replacing the default icon.' },
+ { guidance: false, description: 'Don\'t manually wire isDisabled on XDSChatSendButton inside a composer — the context already tracks whether the input has content. Override only for custom validation logic.' },
+ { guidance: false, description: 'Don\'t use XDSChatSendButton for non-chat submit actions — use XDSButton instead. The send button is purpose-built for the chat composer flow.' },
],
anatomy: [
{ name: 'Message area', required: true, description: 'Scrollable region for messages. Renders children (typically XDSChatMessageList) in a flex column that pushes content to the bottom when the list is short.' },
@@ -289,6 +292,9 @@ export const docsZh = {
{ guidance: false, description: 'Don\'t apply a fixed height directly on XDSChatLayout — wrap it in a sized container and let the layout fill with flex: 1.' },
{ guidance: true, description: 'Show a label on XDSChatLayoutScrollButton (e.g. "New messages") when unread content arrives below the fold so the user knows there is something to see.' },
{ guidance: false, description: 'Don\'t rebuild the scroll-to-bottom button from scratch — use XDSChatLayoutScrollButton or pass a custom element to XDSChatLayout\'s scrollButton prop.' },
+ { guidance: true, description: 'Let XDSChatSendButton read state from XDSChatComposerContext by default — it handles disabled, send, and stop states automatically. Only override via props when using the button standalone or replacing the default icon.' },
+ { guidance: false, description: 'Don\'t manually wire isDisabled on XDSChatSendButton inside a composer — the context already tracks whether the input has content. Override only for custom validation logic.' },
+ { guidance: false, description: 'Don\'t use XDSChatSendButton for non-chat submit actions — use XDSButton instead. The send button is purpose-built for the chat composer flow.' },
],
anatomy: [
{ name: 'Message area', required: true, description: 'Scrollable region for messages. Renders children (typically XDSChatMessageList) in a flex column that pushes content to the bottom when the list is short.' },
@@ -484,6 +490,9 @@ export const docsDense = {
{ guidance: false, description: 'Fixed height on XDSChatLayout directly — wrap in a sized container, let flex: 1 fill.' },
{ guidance: true, description: 'Show a label on XDSChatLayoutScrollButton when unread content arrives below the fold.' },
{ guidance: false, description: 'Don\'t rebuild the scroll-to-bottom button — use XDSChatLayoutScrollButton or pass a custom element to scrollButton.' },
+ { guidance: true, description: 'Let ChatSendButton read context by default. Override only for standalone use or custom icons.' },
+ { guidance: false, description: 'Don\'t manually wire isDisabled on ChatSendButton inside a composer — context already tracks it.' },
+ { guidance: false, description: 'Don\'t use ChatSendButton for non-chat actions — use XDSButton instead.' },
],
},
components: [