useXChat

Manages the messages within a single conversation. A provider must be passed. Without a provider, onRequest and abort throw provider is required.

const {
  onRequest,
  onReload,
  abort,
  messages,
  parsedMessages,
  setMessages,
  setMessage,
  removeMessage,
  isRequesting,
  isDefaultMessagesRequesting,
  queueRequest,
} = useXChat({
  provider,
  conversationKey: activeConversationKey,
  requestPlaceholder: { role: 'assistant', content: '' },
  requestFallback: { role: 'assistant', content: 'failed' },
});

Model integration

Model integration

createOpenAIChatProvider + local SSE mock: input, streaming bubbles, cancel.

<script setup lang="tsx">
defineOptions({ name: 'AXSdkXChatModelV2' });

import { computed, ref } from 'vue';
import {
  Bubble,
  Sender,
  createOpenAIChatProvider,
  useXChat,
  type XModelMessage,
} from 'ant-design-x-vue';
import { Flex } from 'ant-design-vue';
import { XMarkdown } from '@ant-design-x-vue/x-markdown';
import { createMockOpenAIFetch } from '../../_shared/mock-chat';

const input = ref('');
const provider = createOpenAIChatProvider<XModelMessage>({
  baseURL: 'https://mock.local/v1/chat/completions',
  model: 'mock-gpt',
  key: 'docs-preview',
  fetch: createMockOpenAIFetch(),
});

const { onRequest, messages, isRequesting, abort } = useXChat<XModelMessage>({
  provider,
  requestPlaceholder: { role: 'assistant', content: '' },
  requestFallback: { role: 'assistant', content: 'Mock request failed.' },
});

const items = computed(() =>
  messages.value.map((info) => ({
    key: info.id,
    role: info.message?.role === 'user' ? 'user' : 'ai',
    content: typeof info.message?.content === 'string' ? info.message.content : '',
    loading: info.status === 'loading' && !info.message?.content,
  })),
);

defineRender(() => (
  <Flex vertical gap={12} style={{ height: 420 }}>
    <Bubble.List
      style={{ height: 300 }}
      items={items.value}
      roles={{
        user: { placement: 'end' },
        ai: {
          placement: 'start',
          contentRender: (content: string) => <XMarkdown content={content} />,
        },
      }}
    />
    <Sender
      value={input.value}
      loading={isRequesting.value}
      placeholder="Ask the local OpenAI mock"
      onUpdate:value={(v: string) => { input.value = v; }}
      onSubmit={() => {
        const query = input.value.trim();
        if (!query) return;
        input.value = '';
        onRequest({ messages: [{ role: 'user', content: query }], stream: true });
      }}
      onCancel={() => abort()}
    />
  </Flex>
));
</script>

Hide source

Reasoning model integration

Reasoning model integration

DeepSeekChatProvider parses reasoning_content with Think + XMarkdown (still a local mock).

<script setup lang="tsx">
defineOptions({ name: 'AXSdkXChatDeepSeekV2' });

import { computed, ref } from 'vue';
import {
  Bubble,
  Sender,
  Think,
  DeepSeekChatProvider,
  useXChat,
  XRequest,
  type XModelMessage,
  type XModelParams,
} from 'ant-design-x-vue';
import { Flex } from 'ant-design-vue';
import { XMarkdown } from '@ant-design-x-vue/x-markdown';
import { createMockDeepSeekFetch } from '../../_shared/mock-chat';

const input = ref('');
const provider = new DeepSeekChatProvider<XModelMessage, XModelParams>({
  request: XRequest('https://mock.local/v1/chat/completions', {
    manual: true,
    fetch: createMockDeepSeekFetch() as never,
    params: { stream: true, model: 'mock-deepseek' },
  }),
});

const { onRequest, messages, isRequesting, abort } = useXChat<XModelMessage>({
  provider,
  requestPlaceholder: { role: 'assistant', content: '' },
  requestFallback: { role: 'assistant', content: 'Mock request failed.' },
});

const items = computed(() =>
  messages.value.map((info) => ({
    key: info.id,
    role: info.message?.role === 'user' ? 'user' : 'ai',
    content: typeof info.message?.content === 'string' ? info.message.content : '',
    loading: info.status === 'loading' && !info.message?.content,
  })),
);

defineRender(() => (
  <Flex vertical gap={12} style={{ height: 420 }}>
    <Bubble.List
      style={{ height: 300 }}
      items={items.value}
      roles={{
        user: { placement: 'end' },
        ai: {
          placement: 'start',
          contentRender: (content: string) => (
            <XMarkdown content={content} components={{ think: Think }} />
          ),
        },
      }}
    />
    <Sender
      value={input.value}
      loading={isRequesting.value}
      placeholder="Ask the local DeepSeek mock"
      onUpdate:value={(v: string) => { input.value = v; }}
      onSubmit={() => {
        const query = input.value.trim();
        if (!query) return;
        input.value = '';
        onRequest({ messages: [{ role: 'user', content: query }], stream: true });
      }}
      onCancel={() => abort()}
    />
  </Flex>
));
</script>

Hide source

History messages

History messages

Prefill user/assistant history with defaultMessages, then continue.

<script setup lang="tsx">
defineOptions({ name: 'AXSdkXChatDefaultMessagesV2' });

import { computed, ref } from 'vue';
import {
  Bubble,
  Sender,
  createOpenAIChatProvider,
  useXChat,
  type XModelMessage,
} from 'ant-design-x-vue';
import { Flex } from 'ant-design-vue';
import { XMarkdown } from '@ant-design-x-vue/x-markdown';
import { createMockOpenAIFetch } from '../../_shared/mock-chat';

const input = ref('');
const provider = createOpenAIChatProvider<XModelMessage>({
  baseURL: 'https://mock.local/v1/chat/completions',
  model: 'mock-gpt',
  key: 'docs-preview',
  fetch: createMockOpenAIFetch(),
});

const { onRequest, messages, isRequesting, abort } = useXChat<XModelMessage>({
  provider,
  defaultMessages: [
    { message: { role: 'user', content: 'What is Ant Design X?' }, status: 'success' },
    {
      message: {
        role: 'assistant',
        content: 'Ant Design X is a React/Vue AI interaction component library.',
      },
      status: 'success',
    },
  ],
  requestPlaceholder: { role: 'assistant', content: '' },
  requestFallback: { role: 'assistant', content: 'Mock request failed.' },
});

const items = computed(() =>
  messages.value.map((info) => ({
    key: info.id,
    role: info.message?.role === 'user' ? 'user' : 'ai',
    content: typeof info.message?.content === 'string' ? info.message.content : '',
    loading: info.status === 'loading' && !info.message?.content,
  })),
);

defineRender(() => (
  <Flex vertical gap={12} style={{ height: 420 }}>
    <Bubble.List
      style={{ height: 300 }}
      items={items.value}
      roles={{
        user: { placement: 'end' },
        ai: {
          placement: 'start',
          contentRender: (content: string) => <XMarkdown content={content} />,
        },
      }}
    />
    <Sender
      value={input.value}
      loading={isRequesting.value}
      placeholder="Continue from history"
      onUpdate:value={(v: string) => { input.value = v; }}
      onSubmit={() => {
        const query = input.value.trim();
        if (!query) return;
        input.value = '';
        onRequest({ messages: [{ role: 'user', content: query }], stream: true });
      }}
      onCancel={() => abort()}
    />
  </Flex>
));
</script>

Hide source

System prompt

System prompt: None

System prompt

Use role: 'developer' as a system prompt; edit it on the page.

<script setup lang="tsx">
defineOptions({ name: 'AXSdkXChatDeveloperV2' });

import { computed, ref } from 'vue';
import {
  Bubble,
  Sender,
  createOpenAIChatProvider,
  useXChat,
  type XModelMessage,
} from 'ant-design-x-vue';
import { Button, Flex, Typography } from 'ant-design-vue';
import { XMarkdown } from '@ant-design-x-vue/x-markdown';
import { createMockOpenAIFetch } from '../../_shared/mock-chat';

const input = ref('');
const provider = createOpenAIChatProvider<XModelMessage>({
  baseURL: 'https://mock.local/v1/chat/completions',
  model: 'mock-gpt',
  key: 'docs-preview',
  fetch: createMockOpenAIFetch((text) => `System-aware mock reply: ${text || 'hi'}`),
});

const { onRequest, messages, isRequesting, abort, setMessage } = useXChat<XModelMessage>({
  provider,
  defaultMessages: [
    {
      id: 'developer',
      message: { role: 'developer', content: 'You are a helpful chatbot' },
      status: 'local',
    },
  ],
  requestPlaceholder: { role: 'assistant', content: '' },
  requestFallback: { role: 'assistant', content: 'Mock request failed.' },
});

const chatMessages = computed(() =>
  messages.value.filter((m) => (m.message as any)?.role !== 'developer'),
);

const developerPrompt = computed(
  () => messages.value.find((m) => (m.message as any)?.role === 'developer')?.message?.content || 'None',
);

const items = computed(() =>
  chatMessages.value.map((info) => ({
    key: info.id,
    role: info.message?.role === 'user' ? 'user' : 'ai',
    content: typeof info.message?.content === 'string' ? info.message.content : '',
    loading: info.status === 'loading' && !info.message?.content,
  })),
);

defineRender(() => (
  <Flex vertical gap={12} style={{ height: 460 }}>
    <Flex gap={8} align="center" wrap="wrap">
      <Typography.Text>
        System prompt: <code>{String(developerPrompt.value)}</code>
      </Typography.Text>
      <Button
        size="small"
        onClick={() =>
          setMessage('developer', {
            message: { role: 'developer', content: 'Modified system prompt' },
            status: 'local',
          } as any)
        }
      >
        Update system prompt
      </Button>
    </Flex>
    <Bubble.List
      style={{ height: 280 }}
      items={items.value}
      roles={{
        user: { placement: 'end' },
        ai: {
          placement: 'start',
          contentRender: (content: string) => <XMarkdown content={content} />,
        },
      }}
    />
    <Sender
      value={input.value}
      loading={isRequesting.value}
      placeholder="Chat with a system prompt"
      onUpdate:value={(v: string) => { input.value = v; }}
      onSubmit={() => {
        const query = input.value.trim();
        if (!query) return;
        input.value = '';
        onRequest({ messages: [{ role: 'user', content: query }], stream: true });
      }}
      onCancel={() => abort()}
    />
  </Flex>
));
</script>

Hide source

Custom request

Custom request

DefaultChatProvider plus a custom fetch that returns JSON mock data.

<script setup lang="tsx">
defineOptions({ name: 'AXSdkXChatCustomRequestV2' });

import { computed, ref } from 'vue';
import { Bubble, Sender, DefaultChatProvider, useXChat, XRequest } from 'ant-design-x-vue';
import { Flex } from 'ant-design-vue';

interface ChatInput {
  query: string;
}

const sleep = () => new Promise((resolve) => setTimeout(resolve, 1000));

const content = ref('');
const provider = new DefaultChatProvider<string, ChatInput, string>({
  request: XRequest('https://mock.local/chat', {
    manual: true,
    fetch: async (_url, options: any) => {
      await sleep();
      const params = options?.params as ChatInput | undefined;
      return new Response(JSON.stringify([`Mock success return. You said: ${params?.query}`]), {
        headers: { 'Content-Type': 'application/json' },
      });
    },
  }),
});

const { onRequest, messages, isRequesting } = useXChat({
  provider,
  requestPlaceholder: 'Waiting...',
  requestFallback: 'Mock failed return. Please try again later.',
});

const items = computed(() =>
  messages.value.map(({ id, message, status }) => ({
    key: id,
    loading: status === 'loading',
    role: status === 'local' ? 'local' : 'ai',
    content: message,
  })),
);

defineRender(() => (
  <Flex vertical gap="middle">
    <Bubble.List
      style={{ height: 320 }}
      items={items.value}
      roles={{
        ai: { placement: 'start' },
        local: {
          placement: 'end',
          contentRender: (msg: ChatInput | string) =>
            typeof msg === 'string' ? msg : (msg as ChatInput)?.query,
        },
      }}
    />
    <Sender
      loading={isRequesting.value}
      value={content.value}
      onUpdate:value={(v: string) => { content.value = v; }}
      onSubmit={(nextContent: string) => {
        onRequest({ query: nextContent });
        content.value = '';
      }}
    />
  </Flex>
));
</script>

Hide source

API

useXChat

type useXChat<
  ChatMessage extends SimpleType = string,
  ParsedMessage extends SimpleType = ChatMessage,
  Input = RequestParams<ChatMessage>,
  Output = SSEOutput,
> = (config: XChatConfig<ChatMessage, ParsedMessage, Input, Output>) => {
  onRequest: (requestParams: Partial<Input>, opts?: { extraInfo: AnyObject }) => void;
  onReload: (
    id: string | number,
    requestParams: Partial<Input>,
    opts?: { extraInfo: AnyObject },
  ) => void;
  abort: () => void;
  messages: Ref<MessageInfo<ChatMessage>[]>;
  parsedMessages: ComputedRef<MessageInfo<ParsedMessage>[]>;
  setMessages: (...args: Parameters<UseChatStoreReturn['setMessages']>) => void;
  setMessage: (...args: Parameters<UseChatStoreReturn['setMessage']>) => void;
  removeMessage: (id: string | number) => boolean;
  isRequesting: ComputedRef<boolean>;
  isDefaultMessagesRequesting: Ref<boolean>;
  queueRequest: (
    conversationKey: string | symbol,
    requestParams: Partial<Input>,
    opts?: { extraInfo: AnyObject },
  ) => void;
};

XChatConfig

Prop	Description	Type	Default	Version
provider	Data provider, converts data and requests of different structures into a format that can be consumed by useXChat. Built-in DefaultChatProvider, OpenAIChatProvider, or you can inherit AbstractChatProvider to implement it yourself. See Chat Provider	AbstractChatProvider<ChatMessage, Input, Output>	-	-
conversationKey	Conversation key; can be aligned with activeConversationKey of useXConversations to make each conversation independent message	ConversationData['key'] | ShallowRef<ConversationData['key'] | undefined>	-	-
defaultMessages	Display messages by default; support arrays, synchronous functions or asynchronous functions returning Promise (used to pull remote history)	DefaultMessageInfo<ChatMessage>[] | ((info: { conversationKey?: string }) => DefaultMessageInfo<ChatMessage>[] | Promise<DefaultMessageInfo<ChatMessage>[]>)	-	-
parser	Convert ChatMessage to ParsedMessage; if not set, consume ChatMessage directly. Support one-to-many	(message: ChatMessage) => ParsedMessage | ParsedMessage[]	-	-
requestFallback	A cryptic message when the request fails; if not provided, the cryptic message will not be displayed	ChatMessage | ((requestParams: Partial<Input>, info: { error: Error; messages: ChatMessage[]; messageInfo: MessageInfo<ChatMessage> }) => ChatMessage | Promise<ChatMessage>)	-	-
requestPlaceholder	The placeholder message in the request; if not provided, the placeholder will not be displayed	ChatMessage | ((requestParams: Partial<Input>, info: { messages: ChatMessage[] }) => ChatMessage)	-	-

Return

Prop	Description	Type	Default	Version
abort	Cancel request	() => void	-	-
isRequesting	Whether requesting (computed)	ComputedRef<boolean>	-	-
isDefaultMessagesRequesting	Whether the default message list is in the request (asynchronous defaultMessages)	Ref<boolean>	false	-
messages	Currently managed message list	Ref<MessageInfo<ChatMessage>[]>	-	-
parsedMessages	List converted by parser	ComputedRef<MessageInfo<ParsedMessage>[]>	-	-
onReload	Replay by message id, send a request to the backend and update the message with the returned data	(id: string | number, requestParams: Partial<Input>, opts?: { extraInfo: AnyObject }) => void	-	-
onRequest	Append messages and trigger requests	(requestParams: Partial<Input>, opts?: { extraInfo: AnyObject }) => void	-	-
setMessages	Directly modify the message list without triggering a request	(messages | updater) => void	-	-
setMessage	Directly modify a single message without triggering a request	(id, info | updater) => void	-	-
removeMessage	Delete a single message without triggering a request	(id: string | number) => boolean	-	-
queueRequest	Add the request to the queue and wait for the current session defaultMessages to be initialized before sending	(conversationKey: string | symbol, requestParams: Partial<Input>, opts?: { extraInfo: AnyObject }) => void	-	-

MessageInfo

interface MessageInfo<ChatMessage> {
  id: number | string;
  message: ChatMessage;
  status: MessageStatus;
  extraInfo?: AnyObject;
}

MessageStatus

type MessageStatus = 'local' | 'loading' | 'updating' | 'success' | 'error' | 'abort';

useXChat({ agent }) in 1.x is now called useLegacyXChat, and the documentation is in useXChat Data Management.