Ant Design X

https://x.ant.design/
Admin
Ant Design X is an extension of Ant Design focused on crafting superior AI interface solutions and...
Tokens:41,029
Snippets:525
Trust Score:9.6
Update:3 months ago
Show doc for...
Tokens:
Raw
### Install Dependencies and Start Server

Source: https://x.ant.design/docs/react/use-with-vite

Commands to navigate to the project directory, install dependencies, and launch the development server.

```bash
$ cd antdx-demo
$ npm install
$ npm run dev
```

--------------------------------

### Install and Register Skill Library

Source: https://x.ant.design/x-skills/introduce

Commands for global installation and interactive registration of the skill library.

```bash
# Install skill library globally
npm i -g @ant-design/x-skill


# Smart registration to current IDE (interactive installation)
npx x-skill
```

--------------------------------

### Manage Skill Library Versions

Source: https://x.ant.design/x-skills/introduce

Commands to list available versions, install specific versions, and check the installer version.

```bash
# View all available versions
x-skill --list-versions


# or
x-skill -l


# Install specific version (replace <tag> with actual version number)
x-skill --tag <tag>
# or
x-skill -t <tag>


# View current installer version (not skill version)
x-skill --version
# or
x-skill -V
x-skill -v
```

--------------------------------

### Install Dependencies

Source: https://x.ant.design/docs/react/use-with-umi

Install the Umi plugins collection and Ant Design X package.

```bash
$ pnpm i @umijs/plugins -D
$ pnpm i @ant-design/x -S
```

--------------------------------

### Install dependencies

Source: https://x.ant.design/docs/react/contributing

Install project dependencies using npm.

```bash
$ npm install
```

--------------------------------

### Start Development Server

Source: https://x.ant.design/docs/react/use-with-rsbuild

Navigate to the project directory and launch the development server.

```bash
$ cd demo
$ npm run dev
```

--------------------------------

### Install Ant Design X

Source: https://x.ant.design/components/introduce

Use a package manager to install the library into your project.

```bash
$ npm install @ant-design/x --save
```

--------------------------------

### Install X-Card

Source: https://x.ant.design/x-cards/introduce

Install the package using your preferred package manager.

```bash
npm install @ant-design/x-card
# or
yarn add @ant-design/x-card
# or
pnpm add @ant-design/x-card
```

--------------------------------

### Run development server

Source: https://x.ant.design/docs/react/contributing

Start the Ant Design website locally.

```bash
$ npm start
```

--------------------------------

### Start the development server

Source: https://x.ant.design/docs/react/use-with-create-react-app

Navigate to the project directory and launch the local development server.

```bash
$ cd antdx-demo
$ npm run start
```

--------------------------------

### Install SDK Dependencies

Source: https://x.ant.design/~demos/folder-demo-basic

Commands to install or update the required @ant-design/x-sdk version.

```bash
# Auto-prompted fix commands
npm install @ant-design/x-sdk@^2.2.2

# Or install latest version
npm install @ant-design/x-sdk@latest
```

--------------------------------

### Select Umi App Template

Source: https://x.ant.design/docs/react/use-with-umi

Choose the Simple App template during the interactive setup process.

```bash
? Pick Umi App Template › - Use arrow-keys. Return to submit.
❯   Simple App
    Ant Design Pro
    Vue Simple App
```

--------------------------------

### Install Next.js Registry for App Router

Source: https://x.ant.design/docs/react/use-with-next

Install the required registry package to enable style extraction in the App Router.

```bash
$ npm install @ant-design/nextjs-registry --save
```

--------------------------------

### Install @ant-design/x-markdown

Source: https://x.ant.design/x-markdowns/introduce

Use a package manager to add the library to your project dependencies.

```bash
$ npm install @ant-design/x-markdown --save
```

--------------------------------

### Common Usage Commands

Source: https://x.ant.design/x-skills/introduce

Basic commands for installing stable versions, specific versions, and accessing help.

```bash
# Install latest stable version
x-skill


# Install specific version to ensure compatibility
x-skill --tag 2.3.0


# View help information
x-skill --help
```

--------------------------------

### Render with XMarkdown

Source: https://x.ant.design/components/code-highlighter

Example of using XMarkdown to render content.

```typescript
import React from 'react';
import { XMarkdown } from '@ant-design/x-markdown';

const App = () => <XMarkdown content='Hello World' />;
export default App;
```

--------------------------------

### Display HTML Code

Source: https://x.ant.design/components/code-highlighter

Example of rendering an HTML code block.

```html
<!DOCTYPE html>
<html>
<head>
  <title>My Page</title>
</head>
<body>
  <h1>Hello World</h1>
</body>
</html>
```

--------------------------------

### Select Npm Registry

Source: https://x.ant.design/docs/react/use-with-umi

Select the taobao registry for faster dependency installation in China.

```bash
? Pick Npm Registry › - Use arrow-keys. Return to submit.
    npm
❯   taobao
```

--------------------------------

### Minimal Streaming Setup

Source: https://x.ant.design/x-markdowns/streaming

Configure the XMarkdown component with streaming properties and custom loading components for incomplete syntax.

```tsx
<XMarkdown
  content={content}
  streaming={{
    hasNextChunk,
    enableAnimation: true,
    tail: true,
    incompleteMarkdownComponentMap: {
      link: 'link-loading',
      table: 'table-loading',
    },
  }}
  components={{
    'link-loading': LinkSkeleton,
    'table-loading': TableSkeleton,
  }}
/>
```

--------------------------------

### Quick Start with X-Card

Source: https://x.ant.design/x-cards/introduce

Register a component catalog and render an XCard.Box with dynamic commands.

```tsx
import { XCard, registerCatalog } from '@ant-design/x-card';
import type { XAgentCommand_v0_9, Catalog, ActionPayload } from '@ant-design/x-card';


const catalog: Catalog = {
  catalogId: 'my-app-catalog',
  components: {
    Text: {
      /* ... */
    },
    Button: {
      /* ... */
    },
  },
};


registerCatalog(catalog);


const commands: XAgentCommand_v0_9[] = [
  { version: 'v0.9', createSurface: { surfaceId: 'booking', catalogId: 'my-app-catalog' } },
  {
    version: 'v0.9',
    updateComponents: {
      surfaceId: 'booking',
      components: [
        /* ... */
      ],
    },
  },
];


function App() {
  const handleAction = (payload: ActionPayload) => {
    console.log('Action triggered:', payload.name, payload.context);
  };


  return (
    <XCard.Box
      commands={commands}
      onAction={handleAction}
      components={{ Text: MyTextComponent, Button: MyButtonComponent }}
    >
      <XCard.Card id="booking" />
    </XCard.Box>
  );
}
```

--------------------------------

### Install CSS-in-JS for Pages Router

Source: https://x.ant.design/docs/react/use-with-next

Install the CSS-in-JS package for style extraction in the Pages Router.

```bash
$ npm install @ant-design/cssinjs --save
```

--------------------------------

### Display JavaScript Code

Source: https://x.ant.design/components/code-highlighter

Example of rendering a JavaScript code block.

```javascript
import React from 'react';
import { Button } from 'antd';

const App = () => (
  <div>
    <Button type="primary">Primary Button</Button>
  </div>
);

export default App;
```

--------------------------------

### Install Ant Design X SDK

Source: https://x.ant.design/x-sdks/introduce

Use a package manager to add the SDK to your project dependencies.

```bash
$ npm install @ant-design/x-sdk --save
```

--------------------------------

### Display CSS Code

Source: https://x.ant.design/components/code-highlighter

Example of rendering a CSS code block.

```css
.container {
  display: flex;
  justify-content: center;
  align-items: center;
  height: 100vh;
}
```

--------------------------------

### React Counter Example

Source: https://x.ant.design/components/code-highlighter

A basic React counter component snippet.

```javascript
import { useState } from 'react';

function Counter() {
  const [count, setCount] = useState(0);
  return (
    <div>
      <p>当前计数：{count}</p>
      <button onClick={() => setCount(count + 1)}>增加</button>
    </div>
  );
}
```

--------------------------------

### Custom Chat Provider Implementation Example

Source: https://x.ant.design/x-sdks/chat-provider-custom

A complete implementation of a custom provider, demonstrating how to handle input parameters, local message creation, and streaming message transformation.

```typescript
// Type definitions
type CustomInput = {
  query: string;
};


type CustomOutput = {
  data: {
    content: string; // Text content
    attachments?: {
      // Optional: Document attachments
      name: string; // File name
      url: string; // Download link
      type: string; // File type, e.g., 'pdf', 'docx', 'image'
      size?: number; // File size in bytes, optional
    }[];
  };
};


type CustomMessage = {
  content: string;
  role: 'user' | 'assistant';
  // Optional: Attachment information for displaying download links or previews
  attachments?: {
    name: string;
    url: string;
    type: string;
    size?: number;
  }[];
};


class CustomProvider<
  ChatMessage extends CustomMessage = CustomMessage,
  Input extends CustomInput = CustomInput,
  Output extends CustomOutput = CustomOutput,
> extends AbstractChatProvider<ChatMessage, Input, Output> {
  transformParams(
    requestParams: Partial<Input>,
    options: XRequestOptions<Input, Output, ChatMessage>,
  ): Input {
    if (typeof requestParams !== 'object') {
      throw new Error('requestParams must be an object');
    }
    return {
      ...(options?.params || {}),
      ...(requestParams || {}),
    } as Input;
  }
  transformLocalMessage(requestParams: Partial<Input>): ChatMessage {
    return {
      content: requestParams.query,
      role: 'user',
    } as unknown as ChatMessage;
  }
  transformMessage(info: TransformMessage<ChatMessage, Output>): ChatMessage {
    const { originMessage, chunk } = info || {};
    if (!chunk || !chunk?.data || (chunk?.data && chunk?.data?.includes('[DONE]'))) {
      return {
        content: originMessage?.content || '',
        role: 'assistant',
        attachments: originMessage?.attachments || [],
      } as ChatMessage;
    }


    try {
      const data = JSON.parse(chunk.data);
      const content = originMessage?.content || '';


      // Merge attachment information to avoid data loss
      const existingAttachments = originMessage?.attachments || [];
      const newAttachments = data.attachments || [];
      const mergedAttachments = [...existingAttachments];


      // Only add new attachments to avoid duplicates
      newAttachments.forEach((newAttach) => {
        if (!mergedAttachments.some((existing) => existing.url === newAttach.url)) {
          mergedAttachments.push(newAttach);
        }
      });


      return {
        content: `${content || ''}${data.content || ''}`,
        role: 'assistant',
        attachments: mergedAttachments,
      } as ChatMessage;
    } catch {
      // If not JSON format, treat as plain text
      return {
        content: `${originMessage?.content || ''}${chunk.data || ''}`,
        role: 'assistant',
        attachments: originMessage?.attachments || [],
      } as ChatMessage;
    }
  }
}
```

--------------------------------

### Integrate with Claude Code via Marketplace

Source: https://x.ant.design/x-skills/introduce

Commands to add the repository as a plugin source and install the skill package within Claude Code.

```bash
/plugin marketplace add ant-design/x/blob/main/packages/x-skill/
```

```bash
/plugin install x-sdk-skills@x-agent-skills
```

--------------------------------

### Display a message in XMarkdown

Source: https://x.ant.design/x-markdowns/playground

A basic example demonstrating how to render code blocks within the XMarkdown environment.

```tsx
const message = 'Hello, XMarkdown';
console.log(message);
```

--------------------------------

### DefaultChatProvider Usage

Source: https://x.ant.design/x-sdks/chat-provider

Example of instantiating a DefaultChatProvider with an XRequest and integrating it with the useXChat hook.

```APIDOC
## DefaultChatProvider Usage

### Description
Instantiates a DefaultChatProvider to manage requests for useXChat. The provider requires an XRequest call and should be configured with manual=true to allow the hook to control request initiation.

### Implementation Example
```tsx
import { DefaultChatProvider, useXChat, XRequest } from '@ant-design/x-sdk';

const [provider] = React.useState(
  new DefaultChatProvider<string, ChatInput, string>({
    request: XRequest('https://api.example.com/chat', {
      manual: true,
    }),
  }),
);

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

--------------------------------

### Import Bubble Component

Source: https://x.ant.design/docs/react/use-with-vite

Example of importing and using the Bubble component within the App component.

```jsx
import React from 'react';
import { Bubble } from '@ant-design/x';


const App = () => (
  <div className="App">
    <Bubble content="Hello world!" />
  </div>
);


export default App;
```

--------------------------------

### Resolved Action Context Example

Source: https://x.ant.design/x-cards/a2ui-v-0-9

The resulting context object after X-Card resolves path references to actual values.

```json
{
  "username": { "value": "John", "label": "Username" },
  "email": { "value": "john@example.com", "label": "Email" }
}
```

--------------------------------

### Import Bubble component

Source: https://x.ant.design/docs/react/use-with-next

Example of importing and using the Bubble component within a Next.js page file.

```tsx
import React from 'react';
import { Bubble } from '@ant-design/x';


const Home = () => (
  <div className="App">
    <Bubble content="Hello world!" />
  </div>
);


export default Home;
```

--------------------------------

### Initialize Umi Project

Source: https://x.ant.design/docs/react/use-with-umi

Create a new directory and initialize the Umi scaffold.

```bash
$ mkdir myapp && cd myapp
$ pnpm create umi
```

--------------------------------

### Initialize Next.js project

Source: https://x.ant.design/docs/react/use-with-next

Create a new Next.js application using the create-next-app scaffold.

```bash
$ npx create-next-app antdx-demo
```

--------------------------------

### Select Npm Client

Source: https://x.ant.design/docs/react/use-with-umi

Choose pnpm as the package manager for better performance.

```bash
? Pick Npm Client › - Use arrow-keys. Return to submit.
    npm
    cnpm
    tnpm
    yarn
❯   pnpm
```

--------------------------------

### Initialize Vite Project

Source: https://x.ant.design/docs/react/use-with-vite

Command to scaffold a new React project using Vite.

```bash
$ npm create vite antdx-demo
```

--------------------------------

### Initialize Rsbuild Project

Source: https://x.ant.design/docs/react/use-with-rsbuild

Create a new project using the Rsbuild CLI.

```bash
$ npm create rsbuild
```

--------------------------------

### Build the Umi Application

Source: https://x.ant.design/docs/react/use-with-umi

Execute the build command to package all application resources into the dist directory.

```bash
$ npm run build
info  - Umi v4.0.46
✔ Webpack
  Compiled successfully in 5.31s
info  - File sizes after gzip:
  122.45 kB  dist/umi.js
  575 B      dist/src__pages__products.async.js
  312 B      dist/src__pages__index.async.js
  291 B      dist/layouts__index.async.js
  100 B      dist/layouts__index.chunk.css
  55 B       dist/src__pages__products.chunk.css
event - Build index.html
```

--------------------------------

### Initialize React project with TypeScript

Source: https://x.ant.design/docs/react/use-with-create-react-app

Create a new React project scaffold using the TypeScript template.

```bash
$ npx create-react-app antdx-demo --template typescript
```

--------------------------------

### Display Current Conversation Data

Source: https://x.ant.design/x-sdks/use-x-conversations

Example of the JSON structure for a conversation item.

```json
{
  "key": "item1",
  "label": "Conversation Item 1"
}
```

--------------------------------

### Implement Custom ContentType

Source: https://x.ant.design/components/bubble

Example of using a custom type with the Bubble component.

```tsx
type CustomContentType {
  ...
}


<Bubble<CustomContentType> {...props} />
```

--------------------------------

### Welcome Component API

Source: https://x.ant.design/components/welcome

Documentation for the Welcome component properties used to configure the welcome prompt interface.

```APIDOC
## WelcomeProps

### Description
Properties for configuring the Welcome component.

### Properties
- **classNames** (Record<'icon' | 'title' | 'description' | 'extra', string>) - Optional - Custom style class names for different parts of each prompt item.
- **description** (React.ReactNode) - Optional - The description displayed in the prompt list.
- **extra** (React.ReactNode) - Optional - The extra operation displayed at the end of the prompt list.
- **icon** (React.ReactNode) - Optional - The icon displayed on the front side of the prompt list.
- **rootClassName** (string) - Optional - The style class name of the root node.
- **styles** (Record<'icon' | 'title' | 'description' | 'extra', React.CSSProperties>) - Optional - Custom styles for different parts of each prompt item.
- **title** (React.ReactNode) - Optional - The title displayed at the top of the prompt list.
- **variant** ('filled' | 'borderless') - Optional - Variant type. Default: 'filled'.
```

--------------------------------

### Define Surface Data Model

Source: https://x.ant.design/x-cards/introduce

Example of a JSON data model structure for a Surface.

```json
{
  "user": { "name": "Alice", "email": "alice@example.com" },
  "reservation": { "datetime": "2025-12-16T19:00:00Z", "guests": 2 }
}
```

--------------------------------

### Handle TransformStream Error

Source: https://x.ant.design/x-sdks/x-request

Example of the error message encountered when a ReadableStream is already locked.

```ts
onError TypeError: Failed to execute 'getReader' on 'ReadableStream': ReadableStreamDefaultReader constructor can only accept readable streams that are not yet locked to a reader
```

--------------------------------

### Handle Attachments in Requests

Source: https://x.ant.design/x-sdks/chat-provider-custom

Example of sending a request that expects a response containing document attachments.

```tsx
// Send request and handle responses with attachments
onRequest({
  query: 'Generate a project summary report',
});


// The response will include attachment information, which can be displayed as download links in message bubbles
// The messages data will include the attachments field
```

--------------------------------

### Run test suite

Source: https://x.ant.design/docs/react/contributing

Execute the complete test suite. Ensure NODE_ENV is unset to avoid potential issues.

```bash
$ npm test
```

--------------------------------

### Integrate Qwen with X SDK using openai-node

Source: https://x.ant.design/docs/react/model-use-qwen

Demonstrates creating a custom request class extending AbstractXRequestClass to interface with Qwen via the OpenAI SDK. Note that dangerouslyAllowBrowser is used for client-side initialization, which carries security risks.

```tsx
import { Bubble, BubbleListProps, Sender } from '@ant-design/x';
import {
  AbstractXRequestClass,
  OpenAIChatProvider,
  SSEFields,
  useXChat,
  XModelMessage,
  XModelParams,
  XRequestOptions,
} from '@ant-design/x-sdk';
import { Flex } from 'antd';
import OpenAI from 'openai';
import React, { useState } from 'react';


type OutputType = Partial<Record<SSEFields, any>>;
type InputType = XModelParams;


class OpenAiRequest<
  Input extends InputType = InputType,
  Output extends OutputType = OutputType,
> extends AbstractXRequestClass<Input, Output> {
  client: any;
  stream: OpenAI | undefined;


  _isTimeout = false;
  _isStreamTimeout = false;
  _isRequesting = false;


  constructor(baseURL: string, options: XRequestOptions<Input, Output>) {
    super(baseURL, options);
    this.client = new OpenAI({
      baseURL: 'https://dashscope.aliyuncs.com/compatible-mode/v1',
      apiKey: 'OPENAI_API_KEY',
      dangerouslyAllowBrowser: true,
    });
  }
  get asyncHandler(): Promise<any> {
    return Promise.resolve();
  }
  get isTimeout(): boolean {
    return this._isTimeout;
  }
  get isStreamTimeout(): boolean {
    return this._isStreamTimeout;
  }
  get isRequesting(): boolean {
    return this._isRequesting;
  }
  get manual(): boolean {
    return true;
  }
  async run(input: Input): Promise<void> {
    const { callbacks } = this.options;
    try {
      await this.client.responses.create({
        model: 'qwen-plus',
        messages: input?.messages || [],
        stream: true,
      });


      // Please implement stream data update logic based on response
    } catch (error: any) {
      callbacks?.onError(error);
    }
  }
  abort(): void {
    // Please implement abort based on OpenAI
  }
}


const provider = new OpenAIChatProvider<XModelMessage, InputType, OutputType>({
  request: new OpenAiRequest('OPENAI', {}),
});


const Demo: React.FC = () => {
  const [content, setContent] = useState('');
  const { onRequest, messages, isRequesting, abort } = useXChat({
    provider,
    requestPlaceholder: () => {
      return {
        content: 'loading...',
        role: 'assistant',
      };
    },
    requestFallback: (_, { error }) => {
      if (error.name === 'AbortError') {
        return {
          content: 'Request is aborted',
          role: 'assistant',
        };
      }
      return {
        content: error?.toString(),
        role: 'assistant',
      };
    },
  });


  const items = messages.map(({ message, id }) => ({
    key: id,
    ...message,
  }));


  const role: BubbleListProps['role'] = {
    assistant: {
      placement: 'start',
    },
    user: { placement: 'end' },
  };


  return (
    <Flex
      vertical
      justify="space-between"
      style={{
        height: 400,
        padding: 16,
      }}
    >
      <Bubble.List role={role} items={items} />
      <Sender
        value={content}
        onChange={setContent}
        loading={isRequesting}
        onCancel={abort}
        onSubmit={(val) => {
          onRequest({
            messages: [{ role: 'user', content: val }],
          });
          setContent('');
        }}
      />
    </Flex>
  );
};


export default Demo;
```

--------------------------------

### View project directory structure

Source: https://x.ant.design/docs/react/use-with-create-react-app

Standard directory layout generated by create-react-app.

```text
├── README.md
├── package.json
├── public
│   ├── favicon.ico
│   └── index.html
├── src
│   ├── App.css
│   ├── App.js
│   ├── App.test.js
│   ├── index.css
│   ├── index.js
│   └── logo.svg
└── yarn.lock
```

--------------------------------

### Migrate from ConfigProvider

Source: https://x.ant.design/components/x-provider

Shows the necessary changes when replacing antd's ConfigProvider with XProvider.

```diff
- import { ConfigProvider } from 'antd';
+ import { XProvider } from '@ant-design/x';
  const App = () => (
-   <ConfigProvider>
+   <XProvider>
      <YourApp />
-   </ConfigProvider>
+   </XProvider>
  );
```

--------------------------------

### Configure Bubble.List Auto-Scroll

Source: https://x.ant.design/components/bubble

Examples for achieving top-aligned content in Bubble.List using either flexbox or max-height constraints.

```tsx
<div style={{ height: 600, display: 'flex', flexDirection: 'column' }}>
  <Bubble.List items={items} autoScroll />
</div>
```

```tsx
<Bubble.List items={items} autoScroll style={{ maxHeight: 600 }} />
```

--------------------------------

### Compile project

Source: https://x.ant.design/docs/react/contributing

Build TypeScript code into lib and es directories and create UMD build.

```bash
$ npm run compile
```

--------------------------------

### Request and Response Data Format

Source: https://x.ant.design/x-sdks/chat-provider-custom

Example of the JSON request payload and the corresponding server-sent events (SSE) response stream.

```json
{
  "query": "Help me summarize today's tech news"
}
```

```json
id:1
data: {"content":"Okay,"}


id:2
data: {"content":"I'll help you"}


id:3
data: {"content":"summarize today's"}


id:4
data: {"content":"tech news,"}


id:5
data: {"content":"Report has been generated","attachments":[{"name":"Tech News Summary.pdf","url":"https://example.com/download/report.pdf","type":"pdf","size":102400}]}
```

--------------------------------

### Importing Plugins in Browser

Source: https://x.ant.design/x-markdowns/plugins

Use script tags to load pre-built plugin files directly in the browser, accessing them via global variables.

```html
<script src="**/dist/plugins/latex.min.js"></script>
<script>
  const Latex = window.Latex;
</script>
```

--------------------------------

### Access Folder Ref Methods

Source: https://x.ant.design/components/folder

Demonstrates how to access and use imperative methods like getNode, updateNode, deleteNode, and addNode via a component ref.

```tsx
const folderRef = useRef<FolderRef>(null);


// Get a node
const node = folderRef.current?.getNode(['src', 'App.tsx']);


// Rename: immutable update, returns new treeData
const newData = folderRef.current?.updateNode(['src', 'App.tsx'], {
  title: 'Main.tsx',
  path: 'Main.tsx',
});


// Delete a node
const newData = folderRef.current?.deleteNode(['src', 'unused.ts']);


// Add a child node
const newData = folderRef.current?.addNode(['src'], {
  title: 'new.ts',
  path: 'new.ts',
  content: '',
});
```

--------------------------------

### Import Welcome component

Source: https://x.ant.design/components/welcome

Import the Welcome component from the @ant-design/x package to use it in your application.

```typescript
import { Welcome } from "@ant-design/x";
```

--------------------------------

### Migrate Surface Creation

Source: https://x.ant.design/x-cards/introduce

Transition from implicit surface creation to an explicit command sequence.

```typescript
// v0.8: implicit creation
{ updateComponents: { surfaceId: 'booking', catalogId: '...', components: [...] } }


// v0.9: explicit creation
[
  { version: 'v0.9', createSurface: { surfaceId: 'booking', catalogId: '...' } },
  { version: 'v0.9', updateComponents: { surfaceId: 'booking', components: [...] } }
]
```

--------------------------------

### Import XRequest

Source: https://x.ant.design/x-sdks/x-request

Import the XRequest utility from the SDK.

```typescript
import { XRequest } from "@ant-design/x-sdk";
```

--------------------------------

### Define Action Configuration with Path References

Source: https://x.ant.design/x-cards/a2ui-v-0-9

Use the path property within an action's context to bind values from the data model.

```json
{
  "id": "submit-btn",
  "component": "Button",
  "action": {
    "event": {
      "name": "agent:send_context_text",
      "context": {
        "username": { "path": "/form/username", "label": "Username" },
        "email": { "path": "/form/email", "label": "Email" }
      }
    }
  }
}
```

--------------------------------

### Handle Backward Compatibility

Source: https://x.ant.design/x-cards/introduce

Shows how to support both v0.8 and v0.9 command types simultaneously within the XCard.Box component.

```tsx
import type { XAgentCommand_v0_8, XAgentCommand_v0_9 } from '@ant-design/x-card';


// Auto-detect version and handle correctly
const commands: (XAgentCommand_v0_8 | XAgentCommand_v0_9)[] = [
  // v0.8 message
  {
    updateComponents: {
      /* ... */
    },
  },


  // v0.9 message
  {
    version: 'v0.9',
    createSurface: {
      /* ... */
    },
  },
];


<XCard.Box commands={commands}>{/* ... */}</XCard.Box>;
```

--------------------------------

### Check code style

Source: https://x.ant.design/docs/react/contributing

Run the linter to verify code style compliance.

```bash
$ npm run lint
```

--------------------------------

### Instantiate CustomProvider

Source: https://x.ant.design/x-sdks/chat-provider-custom

Initialize the custom provider and hook it into the useXChat state management.

```tsx
const [provider] = React.useState(
  new CustomProvider({
    request: XRequest<CustomInput, CustomOutput>('https://xxx.agent.com/api/stream', {
      manual: true,
    }),
  }),
);


const { onRequest, messages, setMessages, setMessage, isRequesting, abort, onReload } = useXChat({
  provider,
});
```

--------------------------------

### Import OpenAIChatProvider

Source: https://x.ant.design/x-sdks/chat-provider-open-ai

Import the provider from the @ant-design/x-sdk package.

```typescript
import { OpenAIChatProvider } from "@ant-design/x-sdk";
```

--------------------------------

### Configure Chat Provider

Source: https://x.ant.design/~demos/folder-demo-basic

Initialize a custom provider using XRequest with optional request placeholders and error fallback logic.

```typescript
import { MyChatProvider } from './MyChatProvider';
import { XRequest } from '@ant-design/x-sdk';

// Recommended to use XRequest as the default request method
const provider = new MyChatProvider({
  // Default use XRequest, no need for custom fetch
  request: XRequest('https://your-api.com/chat'),
  // When requestPlaceholder is set, placeholder message will be displayed before request starts
  requestPlaceholder: {
    content: 'Thinking...',
    role: 'assistant',
    timestamp: Date.now(),
  },
  // When requestFallback is set, fallback message will be displayed when request fails
  requestFallback: (_, { error, errorInfo, messageInfo }) => {
    if (error.name === 'AbortError') {
      return {
        content: messageInfo?.message?.content || 'Reply cancelled',
        role: 'assistant' as const,
        timestamp: Date.now(),
      };
    }
    return {
      content: errorInfo?.error?.message || 'Network error, please try again later',
      role: 'assistant' as const,
      timestamp: Date.now(),
    };
  },
});
```

--------------------------------

### Import CodeHighlighter

Source: https://x.ant.design/components/code-highlighter

Basic import statement for the component.

```javascript
import { CodeHighlighter } from "@ant-design/x";
```

--------------------------------

### Configure Literal vs Path Binding

Source: https://x.ant.design/x-cards/introduce

Demonstrates static literal values versus dynamic path-based data binding for component properties.

```typescript
// Literal (static)
{ id: 'title', component: 'Text', text: 'Welcome' }


// Path binding (dynamic)
{ id: 'username', component: 'Text', text: { path: '/user/name' } }
```

--------------------------------

### PromptsItemType

Source: https://x.ant.design/components/prompts

Configuration properties for individual prompt items.

```APIDOC
## PromptsItemType

### Properties
- **children** (PromptsItemType[]) - Optional - Nested child prompt items.
- **description** (React.ReactNode) - Optional - Prompt description providing additional information.
- **disabled** (boolean) - Optional - When set to true, click events are disabled. Default: false.
- **icon** (React.ReactNode) - Optional - Prompt icon displayed on the left side of the prompt item.
- **key** (string) - Optional - Unique identifier used to distinguish each prompt item.
- **label** (React.ReactNode) - Optional - Prompt label displaying the main content of the prompt.
```

--------------------------------

### Customize Theme with XProvider

Source: https://x.ant.design/docs/react/use-with-rsbuild

Configure global theme tokens using the XProvider component.

```tsx
import React from 'react';
import { XProvider } from '@ant-design/x';


const App: React.FC = () => (
  <XProvider theme={{ token: { colorPrimary: '#00b96b' } }}>
    <MyApp />
  </XProvider>
);


export default App;
```

--------------------------------

### Generate a new page with Umi CLI

Source: https://x.ant.design/docs/react/use-with-umi

Use the Umi generator to create a new page component and its associated style file.

```bash
$ npx umi g page products
Write: src/pages/products.tsx
Write: src/pages/products.less
```

--------------------------------

### Build a basic chat interface

Source: https://x.ant.design/components/introduce

A simple implementation using Bubble and Sender components to create a chat layout.

```tsx
import React from 'react';
import { Bubble, Sender} from '@ant-design/x';

const messages = [
  {
    content: 'Hello, Ant Design X!',
    role: 'user',
    key: 'user_0',
  },
];

const App = () => (
  <div style={{ height: '400px',display: 'flex', flexDirection: 'column', justifyContent: 'space-between' }}>
    <Bubble.List items={messages} />
    <Sender />
  </div>
);

export default App;
```

--------------------------------

### Implement ProductList Component in Umi

Source: https://x.ant.design/docs/react/use-with-umi

Create a reusable ProductList component in src/components/ProductList.tsx using Ant Design X and Ant Design components.

```tsx
import React from 'react';
import {
  XProvider,
  Bubble,
  Sender,
  Conversations,
  Prompts,
  Suggestion,
  ThoughtChain,
} from '@ant-design/x';
import { Flex, Divider, Radio, Card, Typography } from 'antd';


import type { ConfigProviderProps, GetProp } from 'antd';
import {
  AlipayCircleOutlined,
  BulbOutlined,
  GithubOutlined,
  SmileOutlined,
  UserOutlined,
} from '@ant-design/icons';


export default () => {
  const [value, setValue] = React.useState('');
  const [direction, setDirection] =
    React.useState<GetProp<ConfigProviderProps, 'direction'>>('ltr');


  return (
    <>
      <Flex gap={12} style={{ marginBottom: 16 }} align="center">
        <Typography.Text>Direction:</Typography.Text>
        <Radio.Group value={direction} onChange={(e) => setDirection(e.target.value)}>
          <Radio.Button value="ltr">LTR</Radio.Button>
          <Radio.Button value="rtl">RTL</Radio.Button>
        </Radio.Group>
      </Flex>
      <Card>
        <XProvider direction={direction}>
          <Flex style={{ height: 500 }} gap={12}>
            <Conversations
              style={{ width: 200 }}
              defaultActiveKey="1"
              items={[
                {
                  key: '1',
                  label: 'Conversation - 1',
                  icon: <GithubOutlined />,
                },
                {
                  key: '2',
                  label: 'Conversation - 2',
                  icon: <AlipayCircleOutlined />,
                },
              ]}
            />
            <Divider type="vertical" style={{ height: '100%' }} />
            <Flex vertical style={{ flex: 1 }} gap={8}>
              <Bubble.List
                style={{ flex: 1 }}
                items={[
                  {
                    key: '1',
                    placement: 'end',
                    content: 'Hello Ant Design X!',
                    components: { avatar: <UserOutlined /> },
                  },
                  {
                    key: '2',
                    content: 'Hello World!',
                  },
                ]}
              />
              <Prompts
                items={[
                  {
                    key: '1',
                    icon: <BulbOutlined style={{ color: '#FFD700' }} />,
                    label: 'Ignite Your Creativity',
                  },
                  {
                    key: '2',
                    icon: <SmileOutlined style={{ color: '#52C41A' }} />,
                    label: 'Tell me a Joke',
                  },
                ]}
              />
              <Suggestion items={[{ label: 'Write a report', value: 'report' }]}>
                {({ onTrigger, onKeyDown }) => {
                  return (
                    <Sender
                      value={value}
                      onChange={(nextVal) => {
                        if (nextVal === '/') {
                          onTrigger();
                        } else if (!nextVal) {
                          onTrigger(false);
                        }
                        setValue(nextVal);
                      }}
                      onKeyDown={onKeyDown}
                      placeholder='Type "/" to trigger suggestion'
                    />
                  );
                }}
              </Suggestion>
            </Flex>
          </Flex>
          <ThoughtChain />
        </XProvider>
      </Card>
    </>
  );
};
```

--------------------------------

### Actions.Audio

Source: https://x.ant.design/components/actions

Component for displaying audio playback status.

```APIDOC
## Actions.Audio

### Description
Component for displaying audio playback status.

### Props
- **status** ('loading' | 'error' | 'running' | 'default') - Optional - Playback status, default: 'default'
```

--------------------------------

### Configure App Router Layout

Source: https://x.ant.design/docs/react/use-with-next

Wrap the application children with AntdRegistry in the root layout to inject styles.

```tsx
import React from 'react';
import { AntdRegistry } from '@ant-design/nextjs-registry';


const RootLayout = ({ children }: React.PropsWithChildren) => (
  <html lang="en">
    <body>
      <AntdRegistry>{children}</AntdRegistry>
    </body>
  </html>
);


export default RootLayout;
```

--------------------------------

### Add navigation link to layout

Source: https://x.ant.design/docs/react/use-with-umi

Update the global layout file to include a link to the new products page.

```jsx
<li>
  <Link to="/docs">Docs</Link>
</li>
+ <li>
+   <Link to="/products">Products</Link>
+ </li>
```

--------------------------------

### Import DeepSeekChatProvider

Source: https://x.ant.design/x-sdks/chat-provider-deepseek

Import the provider from the @ant-design/x-sdk package.

```typescript
import { DeepSeekChatProvider } from "@ant-design/x-sdk";
```

--------------------------------

### Configure Pages Router App

Source: https://x.ant.design/docs/react/use-with-next

Wrap the application with XProvider to apply the custom theme.

```tsx
import React from 'react';
import { XProvider } from '@ant-design/x';
import type { AppProps } from 'next/app';


import theme from './theme/themeConfig';


const App = ({ Component, pageProps }: AppProps) => (
  <XProvider theme={theme}>
    <Component {...pageProps} />
  </XProvider>
);


export default App;
```

--------------------------------

### Define v0.9 Surface and Components

Source: https://x.ant.design/x-cards/introduce

Requires explicit versioning and surface creation commands.

```typescript
// Explicitly create Surface
{
  version: 'v0.9',
  createSurface: {
    surfaceId: 'booking',
    catalogId: 'https://example.com/catalogs/booking/v1/catalog.json'
  }
}


// Update components
{
  version: 'v0.9',
  updateComponents: {
    surfaceId: 'booking',
    components: [
      {
        id: 'root',
        component: 'Column',
        children: ['header', 'content']
      }
    ]
  }
}
```

--------------------------------

### useXChat(config)

Source: https://x.ant.design/x-sdks/use-x-chat

The useXChat hook initializes a chat session and returns methods and state for managing messages and requests.

```APIDOC
## useXChat

### Description
Initializes the chat hook with a configuration object to manage message state, request logic, and data parsing.

### Signature
`useXChat<ChatMessage, ParsedMessage, Input, Output>(config: XChatConfig<ChatMessage, ParsedMessage, Input, Output>) => XChatConfigReturnType`

### Configuration (XChatConfig)
- **provider** (AbstractChatProvider) - Required - Data provider for converting requests and responses.
- **conversationKey** (string) - Optional - Globally unique session identifier.
- **defaultMessages** (MessageInfo[] | Function) - Optional - Initial messages to display.
- **parser** (Function) - Optional - Converts ChatMessage into ParsedMessage for consumption.
- **requestFallback** (ChatMessage | Function) - Optional - Fallback message for failed requests.
- **requestPlaceholder** (ChatMessage | Function) - Optional - Placeholder message during active requests.

### Return Value (XChatConfigReturnType)
- **abort** (Function) - Cancels the current request.
- **isRequesting** (boolean) - Indicates if a request is in progress.
- **isDefaultMessagesRequesting** (boolean) - Indicates if default messages are loading.
- **messages** (MessageInfo[]) - Current list of managed messages.
- **parsedMessages** (MessageInfo[]) - Messages processed by the parser.
- **onReload** (Function) - Regenerates a message by sending a new request.
- **onRequest** (Function) - Adds a message and triggers a request.
- **setMessages** (Function) - Updates the message list without triggering requests.
- **setMessage** (Function) - Updates a single message by ID.
- **removeMessage** (Function) - Removes a message by ID.
- **queueRequest** (Function) - Queues a request until the conversationKey is initialized.
```

--------------------------------

### streaming

Source: https://x.ant.design/x-markdowns/streaming

Configuration object for streaming rendering behavior in the XMarkdown component.

```APIDOC
## streaming

### Description
Configuration object passed to the XMarkdown component to control streaming behavior.

### Parameters
- **hasNextChunk** (boolean) - Optional - Whether more chunks are coming. Default: false.
- **incompleteMarkdownComponentMap** (Partial<Record<Exclude<StreamCacheTokenType, 'text'>, string>>) - Optional - Component mapping for incomplete syntax. Default: {}.
- **enableAnimation** (boolean) - Optional - Enable fade-in animation. Default: false.
- **animationConfig** (AnimationConfig) - Optional - Animation configuration. Default: { fadeDuration: 200, easing: 'ease-in-out' }.
- **tail** (boolean | TailConfig) - Optional - Enable tail indicator. Default: false.
```

--------------------------------

### Import XProvider

Source: https://x.ant.design/components/x-provider

Basic import statement for the XProvider component.

```typescript
import { XProvider } from "@ant-design/x";
```

--------------------------------

### Catalog Management Methods

Source: https://x.ant.design/x-cards/a2ui-v-0-9

Methods for registering, loading, validating, and clearing component catalogs.

```typescript
registerCatalog(catalog: Catalog): void
```

```typescript
loadCatalog(catalogId: string): Promise<Catalog>
```

```typescript
validateComponent(catalog: Catalog, componentName: string, componentProps: Record<string, any>): boolean
```

```typescript
clearCatalogCache(): void
```

--------------------------------

### Define Custom Theme

Source: https://x.ant.design/docs/react/use-with-next

Create a theme configuration object to customize Ant Design tokens.

```ts
// theme/themeConfig.ts
import type { ThemeConfig } from 'antd';


const theme: ThemeConfig = {
  token: {
    fontSize: 16,
    colorPrimary: '#52c41a',
  },
};


export default theme;
```

--------------------------------

### Import useXConversations

Source: https://x.ant.design/x-sdks/use-x-conversations

Import the hook from the @ant-design/x-sdk package.

```typescript
import { useXConversations } from "@ant-design/x-sdk";
```

--------------------------------

### loadCatalog

Source: https://x.ant.design/x-cards/a2ui-v-0-9

Loads a component catalog from a remote URL or a locally registered schema.

```APIDOC
## loadCatalog

### Description
Loads a catalog definition. Supports remote URLs or locally registered identifiers.

### Signature
`loadCatalog(catalogId: string): Promise<Catalog>`

### Parameters
- **catalogId** (string) - Required - The URL or identifier of the catalog.
```

--------------------------------

### Adapt Ant Design X components for mobile

Source: https://x.ant.design/docs/react/faq

Use the size prop set to small and customize theme components via ConfigProvider to optimize the interface for mobile devices.

```tsx
import { Bubble, Sender } from '@ant-design/x';
import { ConfigProvider } from 'antd';


const App = () => (
  <ConfigProvider
    theme={{
      components: {
        // You can customize mobile styles here
      },
    }}
  >
    <Bubble.List
      items={messages}
      size="small" // Use small size for mobile
    />
    <Sender placeholder="Please enter..." size="small" />
  </ConfigProvider>
);
```

--------------------------------

### Initialize and use Tbox client for streaming chat

Source: https://x.ant.design/docs/react/agent-use-tbox

Configures the Tbox client with authorization credentials and handles streaming responses from the chat API.

```typescript
import { TboxClient } from 'tbox-nodejs-sdk';


const client = new TboxClient({
  httpClientConfig: {
    authorization: 'Tbox-your-token-xxx',
  },
});


const stream = client.chat({
  appId: 'your-app-id',
  query: '今天杭州天气怎么样？',
  userId: 'user123',
});


stream.on('data', (data) => {
  console.log('Received data:', data);
});


stream.on('end', () => {
  console.log('Stream ended');
});


stream.on('error', (error) => {
  console.error('Stream error:', error);
});
```

--------------------------------

### AnimationConfig

Source: https://x.ant.design/x-markdowns/streaming

Configuration for fade-in animations during streaming.

```APIDOC
## AnimationConfig

### Description
Configuration for fade-in animation settings.

### Properties
- **fadeDuration** (number) - Optional - Duration in ms. Default: 200.
- **easing** (string) - Optional - CSS easing function. Default: 'ease-in-out'.
```

--------------------------------

### createSurface

Source: https://x.ant.design/x-cards/introduce

Creates a new UI container (Surface) with an independent component tree and data model.

```APIDOC
## createSurface

### Description
Creates a new UI container (Surface). Each Surface has its own independent component tree and data model.

### Request Body
- **version** (string) - Required - Protocol version, must be 'v0.9'
- **createSurface** (object) - Required
  - **surfaceId** (string) - Required - Unique surface identifier
  - **catalogId** (string) - Required - URL to the component catalog
```

--------------------------------

### Perform Batch Data Updates

Source: https://x.ant.design/x-cards/introduce

Demonstrates the transition from multiple v0.8 messages to a single v0.9 message for updating data models.

```typescript
// v0.8: multiple messages required
[
  { updateDataModel: { surfaceId: 'booking', contents: [{ op: 'add', path: '/date', value: '2025-12-16' }] } },
  { updateDataModel: { surfaceId: 'booking', contents: [{ op: 'add', path: '/guests', value: 2 }] } }
]


// v0.9: one message is enough
{
  version: 'v0.9',
  updateDataModel: {
    surfaceId: 'booking',
    path: '/reservation',
    value: { date: '2025-12-16', guests: 2 }
  }
}
```
Tokens:
Raw