Bubble
Bubble
A bubble component for chat.
Importimport { Bubble } from "@ant-design/x"; |
Sourcecomponents/bubble |
Docs |
Ant Design XImportimport { Bubble } from "@ant-design/x"; |
Sourcecomponents/bubble |
Docs |
Often used in chat scenarios.
Common Props Reference: Common Props
| Attribute | Description | Type | Default | Version |
|---|---|---|---|---|
| placement | Bubble position | start | end | start | - |
| loading | Loading state | boolean | - | - |
| loadingRender | Custom loading content renderer | () => React.ReactNode | - | - |
| content | Bubble content | ContentType | - | - |
| contentRender | Custom content renderer | (content: ContentType, info: InfoType ) => React.ReactNode | - | - |
| editable | Editable | boolean | EditableBubbleOption | false | - |
| typing | Typing animation effect | boolean | BubbleAnimationOption | ((content: ContentType, info: InfoType) => boolean | BubbleAnimationOption) | false | - |
| streaming | Streaming mode | boolean | false | - |
| variant | Bubble style variant | filled | outlined | shadow | borderless | filled | - |
| shape | Bubble shape | default | round | corner | default | - |
| footerPlacement | Footer slot position | outer-start | outer-end | inner-start | inner-end | outer-start | - |
| components | Slot configuration | { header?: BubbleSlot; footer?: BubbleSlot; avatar?: BubbleSlot; extra?: BubbleSlot; } | - | - |
| onTyping | Typing animation callback | (rendererContent: string, currentContent: string) => void | - | - |
| onTypingComplete | Typing animation complete callback | (content: string) => void | - | - |
| onEditing | Callback when content changes in editing mode | (content: string) => void | - | - |
Default type
type ContentType = React.ReactNode | AnyObject | string | number;
Custom type usage
type CustomContentType {...}<Bubble<CustomContentType> {...props} />
type BubbleSlot<ContentType> =| React.ReactNode| ((content: ContentType, info: InfoType) => React.ReactNode);
interface EditableBubbleOption {/*** @description Whether editable*/editing?: boolean;/*** @description OK button*/okText?: React.ReactNode;/*** @description Cancel button*/cancelText?: React.ReactNode;}
interface BubbleAnimationOption {/*** @description Animation effect type, typewriter, fade-in* @default 'fade-in'*/effect: 'typing' | 'fade-in';/*** @description Content step unit, array format for random interval* @default 6*/step?: number | [number, number];/*** @description Animation trigger interval* @default 100*/interval?: number;/*** @description Whether to keep the common prefix when restarting animation* @default true*/keepPrefix?: boolean;/*** @description Suffix UI for typewriter effect* @default undefined*/suffix?: React.ReactNode;}
streaming notifies Bubble whether the current content is streaming input. In streaming mode, regardless of whether Bubble input animation is enabled, Bubble will not trigger the onTypingComplete callback until streaming becomes false, even if the current content is fully output. Only when streaming becomes false and the content is fully output will Bubble trigger onTypingComplete. This avoids multiple triggers due to unstable streaming and ensures only one trigger per streaming process.
In this example, you can try to force the streaming flag off:
onTypingComplete may occur because streaming speed cannot keep up with animation speed.onTypingComplete.| Attribute | Description | Type | Default | Version |
|---|---|---|---|---|
| items | Bubble data list, key and role required. When used with X SDK useXChat, you can pass status to help Bubble manage configuration | (BubbleProps & { key: string | number, role: string , status: MessageStatus, extra?: AnyObject })[] | - | - |
| autoScroll | Auto-scroll | boolean | true | - |
| role | Role default configuration | RoleType | - | - |
type MessageStatus = 'local' | 'loading' | 'updating' | 'success' | 'error' | 'abort';
When used in conjunction with useXChat, key can be used as MessageId,and extra can be used as a custom parameter.
type InfoType = {status?: MessageStatus;key?: string | number;extra?: AnyObject;};
export type RoleProps = Pick<BubbleProps<any>,| 'typing'| 'variant'| 'shape'| 'placement'| 'rootClassName'| 'classNames'| 'className'| 'styles'| 'style'| 'loading'| 'loadingRender'| 'contentRender'| 'footerPlacement'| 'components'| 'editable'| 'onTyping'| 'onTypingComplete'| 'onEditConfirm'| 'onEditCancel'>;export type FuncRoleProps = (data: BubbleItemType) => RoleProps;export type DividerRoleProps = Partial<DividerBubbleProps>;export type FuncDividerRoleProps = (data: BubbleItemType) => DividerRoleProps;export type RoleType = Partial<'ai' | 'system' | 'user', RoleProps | FuncRoleProps>> & { divider: DividerRoleProps | FuncDividerRoleProps } & Record<string,RoleProps | FuncRoleProps>;
Bubble.List auto-scroll is a simple reverse sorting scheme. In a fixed-height Bubble.List, if the message content is insufficient to fill the height, the content is bottom-aligned. It is recommended not to set a fixed height for Bubble.List, but to set a fixed height for its parent container and use flex layout (display: flex and flex-direction: column). This way, Bubble.List adapts its height and aligns content to the top when content is sparse, as shown in the Bubble List demo.
<div style={{ height: 600, display: 'flex', flexDirection: 'column' }}><Bubble.List items={items} autoScroll /></div>
If you do not want to use flex layout, you can set max-height for Bubble.List. When content is sparse, the height adapts and aligns to the top.
<Bubble.List items={items} autoScroll style={{ maxHeight: 600 }} />
Both the role and items attributes of Bubble.List can be configured for bubbles, where the role configuration is used as the default and can be omitted. item.role is used to specify the bubble role for the data item, which will be matched with Bubble.List.role. The items itself can also be configured with bubble attributes, with higher priority than the role configuration. The final bubble configuration is: { ...role[item.role], ...item }.
Special note: We provide four default fields for role, ai, user, system, divider. Among these, system and divider are reserved fields. If item.role is assigned either of them, Bubble.List will render this bubble data as Bubble.System (role = 'system') or Bubble.Divider (role = 'divider').
Therefore, if you want to customize the rendering of system Bubble or divider Bubble, you should use other names.
Customize the rendering Bubble, you can refer to the rendering method of reference in this example.
Common Props Reference: Common Props
| Attribute | Description | Type | Default | Version |
|---|---|---|---|---|
| content | Bubble content | ContentType | - | - |
| variant | Bubble style variant | filled | outlined | shadow | borderless | shadow | - |
| shape | Bubble shape | default | round | corner | default | - |
Common Props Reference: Common Props
| Attribute | Description | Type | Default | Version |
|---|---|---|---|---|
| content | Bubble content，same as Divider.children | ContentType | - | - |
| dividerProps | Divider props | Divider | - | - |
Basic usage.
variant and shape, borderless Bubble is suitable for rendering custom-styled content.
Bubble sidebar and placement, placement will change the position of the primary and secondary sidebars.
Bubble of system information.
Bubble of divider.
Bubble header, placement will change the alignment of the header.
Bubble footer, not affected by placement, use footerPlacement to control the rendering position of the footer.
Control the loading state by loading prop.
Animation effect. It only works if content is a string or contentRender renders a string. Non-string scenes require custom rendering animations. When it takes effect, if content remains unchanged and other configurations change, the animation does not re-execute.
Stream. streaming can be passed to tell Bubble if the current content is a streaming input.
Custom rendering content.
Cooperate with x-markdown to achieve customized rendering content.
Editable bubble, support simple editing of string type content, and should be protected by XSS in onEditing when used.
Cooperate with @antv/GPT-Vis to achieve customized rendering chart of LLM stream output.
Bubble list with preset styles, supports automatic scrolling, supports using role to define different types of bubbles and set properties. Bubble.List is a controlled component, and Bubble is internally memoized, so it is recommended to use setState callback form to modify the items property, and try to ensure the stability of the configuration of non-essential rendering data items, so as to ensure the high performance rendering of Bubble.List.
Bubble.List ref.
Sample for adjusting the bubble effect through semantic and loading customization.
Implement custom extension capabilities in conjunction with extension parameters.
