useXConversations

Manage session list and current session. conversations and activeConversationKey are shallowRef, and after matching with conversationKey of useXChat, each conversation has its own message.

const {
  conversations,
  activeConversationKey,
  setActiveConversationKey,
  addConversation,
  removeConversation,
  setConversation,
  setConversations,
  getConversation,
  getMessages,
} = useXConversations({
  defaultConversations: [{ key: '1', label: 'New chat' }],
  defaultActiveConversationKey: '1',
});

addConversation(conversation, 'prepend' | 'append'). The conversation object must have at least a key.

Basic usage

• Conversation Item 1
• Conversation Item 2
• This's Conversation Item 3, you can click me!
• Conversation Item 4

Basic usage

Uses useXConversations to drive the conversation list.

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

import { computed } from 'vue';
import type { ConversationsProps } from 'ant-design-x-vue';
import { Conversations, useXConversations } from 'ant-design-x-vue';
import { Flex, theme } from 'ant-design-vue';

const items: ConversationsProps['items'] = Array.from({ length: 4 }).map((_, index) => ({
  key: `item${index + 1}`,
  label:
    index + 1 === 3
      ? "This's Conversation Item 3, you can click me!"
      : `Conversation Item ${index + 1}`,
  disabled: index === 3,
}));

const { conversations } = useXConversations({ defaultConversations: items });
const { token } = theme.useToken();
const style = computed(() => ({
  width: '256px',
  background: token.value.colorBgContainer,
  borderRadius: `${token.value.borderRadius}px`,
}));

defineRender(() => (
  <Flex vertical gap="small" align="flex-start">
    <Conversations
      items={conversations.value as ConversationsProps['items']}
      defaultActiveKey="item1"
      style={style.value}
    />
  </Flex>
));
</script>

Hide source

Conversation actions

• Conversation Item 1
• Conversation Item 2
• This's Conversation Item 3, you can click me!
• Conversation Item 4

Current Conversation Data:

{
  "key": "item1",
  "label": "Conversation Item 1",
  "disabled": false
}

Conversation actions

Create, update, reset, and delete from the menu.

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

import { computed, ref } from 'vue';
import { DeleteOutlined } from '@ant-design/icons-vue';
import type { ConversationsProps } from 'ant-design-x-vue';
import { Conversations, useXConversations } from 'ant-design-x-vue';
import { Button, Flex, Typography, theme } from 'ant-design-vue';

const { Paragraph } = Typography;

const createItems = (): NonNullable<ConversationsProps['items']> =>
  Array.from({ length: 4 }).map((_, index) => ({
    key: `item${index + 1}`,
    label:
      index + 1 === 3
        ? "This's Conversation Item 3, you can click me!"
        : `Conversation Item ${index + 1}`,
    disabled: index === 3,
  }));

const idx = ref(5);
const {
  conversations,
  addConversation,
  activeConversationKey,
  setActiveConversationKey,
  setConversation,
  removeConversation,
  getConversation,
  setConversations,
} = useXConversations({
  defaultConversations: createItems(),
  defaultActiveConversationKey: 'item1',
});

const { token } = theme.useToken();
const style = computed(() => ({
  width: '256px',
  background: token.value.colorBgContainer,
  borderRadius: `${token.value.borderRadius}px`,
}));

const onAdd = () => {
  addConversation({ key: `item${idx.value}`, label: `Conversation Item ${idx.value}` });
  idx.value += 1;
};

const onUpdate = () => {
  setConversation(activeConversationKey.value!, {
    key: activeConversationKey.value!,
    label: 'Updated Conversation Item',
  });
};

const onReset = () => {
  setConversations(createItems());
  setActiveConversationKey('item1');
};

const menuConfig: ConversationsProps['menu'] = (conversation) => ({
  items: [
    {
      label: 'Delete',
      key: 'delete',
      icon: <DeleteOutlined />,
      danger: true,
    },
  ],
  onClick: () => {
    removeConversation(conversation.key);
  },
});

defineRender(() => (
  <Flex vertical gap="small" align="flex-start">
    <Conversations
      creation={{ onClick: onAdd }}
      items={conversations.value as ConversationsProps['items']}
      activeKey={activeConversationKey.value}
      style={style.value}
      onActiveChange={setActiveConversationKey}
      menu={menuConfig}
    />
    <Flex gap="small">
      <Button onClick={onAdd}>Add</Button>
      <Button onClick={onUpdate}>Update</Button>
      <Button onClick={onReset}>Reset</Button>
    </Flex>
    <Paragraph>
      Current Conversation Data:
      <pre>{JSON.stringify(getConversation(activeConversationKey.value!), null, 2)}</pre>
    </Paragraph>
  </Flex>
));
</script>

Hide source

Multiple instances

List 1

• Conversation Item 1
• Conversation Item 2
• This's Conversation Item 3, you can click me!
• Conversation Item 4

List 2

• Conversation Item 1
• Conversation Item 2

Multiple instances

Two independent useXConversations instances do not affect each other.

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

import { computed, ref } from 'vue';
import { DeleteOutlined } from '@ant-design/icons-vue';
import type { ConversationsProps } from 'ant-design-x-vue';
import { Conversations, useXConversations } from 'ant-design-x-vue';
import { Button, Col, Flex, Row, theme } from 'ant-design-vue';

const items: ConversationsProps['items'] = Array.from({ length: 4 }).map((_, index) => ({
  key: `item${index + 1}`,
  label:
    index + 1 === 3
      ? "This's Conversation Item 3, you can click me!"
      : `Conversation Item ${index + 1}`,
  disabled: index === 3,
}));

const others: ConversationsProps['items'] = Array.from({ length: 2 }).map((_, index) => ({
  key: `other${index + 1}`,
  label: `Conversation Item ${index + 1}`,
  disabled: index === 3,
}));

const idx = ref(5);
const otherIdx = ref(3);

const handler = useXConversations({
  defaultConversations: items as any,
  defaultActiveConversationKey: items![0].key,
});
const otherHandler = useXConversations({
  defaultConversations: others as any,
  defaultActiveConversationKey: others![0].key,
});

const { token } = theme.useToken();
const style = computed(() => ({
  width: '256px',
  background: token.value.colorBgContainer,
  borderRadius: `${token.value.borderRadius}px`,
}));

const onAdd = (type?: string) => {
  const instance = type === 'other' ? otherHandler : handler;
  const n = type === 'other' ? otherIdx.value : idx.value;
  instance.addConversation({
    key: `${type === 'other' ? 'other' : 'item'}${n}`,
    label: `Conversation Item ${n}`,
  });
  if (type === 'other') otherIdx.value += 1;
  else idx.value += 1;
};

const onUpdate = (type?: string) => {
  const instance = type === 'other' ? otherHandler : handler;
  const realActive =
    type === 'other' ? otherHandler.activeConversationKey.value! : handler.activeConversationKey.value!;
  instance.setConversation(realActive, { key: realActive, label: 'Updated Conversation Item' });
};

const menuConfig: ConversationsProps['menu'] = (conversation) => ({
  items: [{ label: 'Delete', key: 'delete', icon: <DeleteOutlined />, danger: true }],
  onClick: () => handler.removeConversation(conversation.key),
});

const otherMenuConfig: ConversationsProps['menu'] = (conversation) => ({
  items: [{ label: 'Delete', key: 'delete', icon: <DeleteOutlined />, danger: true }],
  onClick: () => otherHandler.removeConversation(conversation.key),
});

defineRender(() => (
  <Flex vertical gap="small" align="flex-start">
    <Row gutter={36}>
      <Col>
        <h3>List 1</h3>
        <Conversations
          items={handler.conversations.value as ConversationsProps['items']}
          activeKey={handler.activeConversationKey.value}
          style={style.value}
          onActiveChange={handler.setActiveConversationKey}
          menu={menuConfig}
        />
        <Flex gap="small" style={{ marginTop: 8 }}>
          <Button onClick={() => onAdd()}>Add</Button>
          <Button onClick={() => onUpdate()}>Update</Button>
        </Flex>
      </Col>
      <Col>
        <h3>List 2</h3>
        <Conversations
          items={otherHandler.conversations.value as ConversationsProps['items']}
          activeKey={otherHandler.activeConversationKey.value}
          style={style.value}
          onActiveChange={otherHandler.setActiveConversationKey}
          menu={otherMenuConfig}
        />
        <Flex gap="small" style={{ marginTop: 8 }}>
          <Button onClick={() => onAdd('other')}>Add</Button>
          <Button onClick={() => onUpdate('other')}>Update</Button>
        </Flex>
      </Col>
    </Row>
  </Flex>
));
</script>

Hide source

Use with useXChat

• Conversation Item 1
• Conversation Item 2
• This's Conversation Item 3, you can click me!
• Conversation Item 4

Use with useXChat

Messages stay under each conversation key; requests use a local mock, not an external API key.

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

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

const items: ConversationsProps['items'] = Array.from({ length: 4 }).map((_, index) => ({
  key: `item${index + 1}`,
  label:
    index + 1 === 3
      ? "This's Conversation Item 3, you can click me!"
      : `Conversation Item ${index + 1}`,
  disabled: index === 3,
}));

const getDefaultMessages = (conversationKey: string) => {
  const messagesMap: Record<string, any[]> = {
    item1: [
      { message: { role: 'user', content: 'Hello, this is Conversation 1!' }, status: 'success' },
      {
        message: {
          role: 'assistant',
          content: 'Hello! This is the welcome message for Conversation 1.',
        },
        status: 'success',
      },
    ],
    item2: [
      { message: { role: 'user', content: 'Conversation 2 has started' }, status: 'success' },
      {
        message: {
          role: 'assistant',
          content: 'Welcome to Conversation 2! We can discuss technology topics.',
        },
        status: 'success',
      },
    ],
    item3: [
      { message: { role: 'user', content: 'Clicked on Conversation 3' }, status: 'success' },
      {
        message: {
          role: 'assistant',
          content: 'You selected Conversation 3! How can I help you?',
        },
        status: 'success',
      },
    ],
    item4: [
      { message: { role: 'user', content: 'Conversation 4 initialized' }, status: 'success' },
      {
        message: {
          role: 'assistant',
          content: 'This is Conversation 4. You can still view historical messages.',
        },
        status: 'success',
      },
    ],
  };
  return (
    messagesMap[conversationKey] || [
      { message: { role: 'user', content: 'hello!' }, status: 'success' },
      {
        message: { role: 'assistant', content: 'Hello! How can I assist you today?' },
        status: 'success',
      },
    ]
  );
};

const {
  conversations,
  activeConversationKey,
  setActiveConversationKey,
} = useXConversations({
  defaultConversations: items,
  defaultActiveConversationKey: 'item1',
});

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

const input = ref('');
const chat = useXChat<XModelMessage>({
  provider,
  conversationKey: activeConversationKey,
  defaultMessages: getDefaultMessages(String(activeConversationKey.value || 'item1')),
  requestPlaceholder: { role: 'assistant', content: '' },
  requestFallback: { role: 'assistant', content: 'Mock request failed.' },
});

const bubbles = computed(() =>
  chat.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,
  })),
);

const { token } = theme.useToken();
const listStyle = computed(() => ({
  width: '220px',
  background: token.value.colorBgContainer,
  borderRadius: `${token.value.borderRadius}px`,
}));

function send() {
  const query = input.value.trim();
  if (!query || chat.isRequesting.value) return;
  input.value = '';
  chat.onRequest({
    messages: [{ role: 'user', content: query }],
    stream: true,
  });
}

defineRender(() => (
  <Flex gap={16} style={{ height: 420 }}>
    <Conversations
      style={listStyle.value}
      items={conversations.value as ConversationsProps['items']}
      activeKey={activeConversationKey.value}
      onActiveChange={(key: string) => setActiveConversationKey(key)}
    />
    <Flex vertical gap={12} style={{ flex: 1, minWidth: 0 }}>
      <Bubble.List
        style={{ flex: 1, minHeight: 0, height: 300 }}
        items={bubbles.value}
        roles={{
          user: { placement: 'end' },
          ai: {
            placement: 'start',
            contentRender: (content: string) => <XMarkdown content={content} />,
          },
        }}
      />
      <Sender
        value={input.value}
        loading={chat.isRequesting.value}
        placeholder="Ask the local mock"
        onUpdate:value={(v: string) => { input.value = v; }}
        onSubmit={send}
        onCancel={() => chat.abort()}
      />
    </Flex>
  </Flex>
));
</script>

Hide source

API

useXConversations

type useXConversations = (config?: XConversationConfig) => {
  conversations: ShallowRef<ConversationData[]>;
  activeConversationKey: ShallowRef<string>;
  setActiveConversationKey: (key: string) => boolean;
  addConversation: (conversation: ConversationData, placement?: 'prepend' | 'append') => boolean;
  removeConversation: (key: string) => boolean;
  setConversation: (key: string, conversation: ConversationData) => boolean;
  getConversation: (key: string) => ConversationData | undefined;
  setConversations: (conversations: ConversationData[]) => boolean;
  getMessages: (conversationKey: string) => unknown;
};

XConversationConfig

Prop	Description	Type	Default	Version
defaultConversations	Default conversation list	ConversationData[]	[]	-
defaultActiveConversationKey	Default current conversation key	string	''	-

ConversationData

interface ConversationData extends AnyObject {
  key: string;
  label?: string;
}

Return

Prop	Description	Type	Default	Version
conversations	Conversation list (shallowRef)	ShallowRef<ConversationData[]>	-	-
activeConversationKey	Current conversation key (shallowRef)	ShallowRef<string>	-	-
setActiveConversationKey	Switch current conversation	(key: string) => boolean	-	-
addConversation	Add a new conversation	(conversation: ConversationData, placement?: 'prepend'	'append') => boolean	-
removeConversation	Remove a conversation	(key: string) => boolean	-	-
setConversation	Update a single conversation	(key: string, conversation: ConversationData) => boolean	-	-
getConversation	Get a conversation by key	(key: string) => ConversationData	undefined	-
setConversations	Replace the entire conversation list	(conversations: ConversationData[]) => boolean	-	-
getMessages	Read message snapshots by conversation key	(conversationKey: string) => unknown	-	-