Bubble

• A chat with an AI assistant, where replies stream in and may hold Markdown, code or charts.
• A support or team thread, where who said what matters and each message carries a name, a time or an avatar.
• A message the reader can act on: copy, retry, rate or edit it from the footer.

Use something else when

• The text is a status for the page, not a turn in a conversation. That is an Alert.
• The text is a hint attached to a control. That is a Tooltip or a Popover.
• The list is a feed of comments or events with no back and forth. A plain list or a Timeline reads better than a column of bubbles.

• In Bubble.List, set it once per role in the role map rather than on every item.
• In a thread with more than two people, side alone does not say who spoke. Add an avatar or a header with the name.
• The avatar, the speech corner of shape="corner" and the default footer all follow placement, so you do not have to mirror them yourself.

• filled suits short messages from the reader. outlined or borderless suits long AI answers, where a heavy fill behind several paragraphs gets tiring.
• shadow lifts the bubble off a busy background, and it is the default for Bubble.System.
• round suits one-line messages. On a message that wraps to several lines, the pill shape turns into a rounded box anyway.

• loading covers the wait before the first token. Turn it off as soon as text arrives, or the reader stares at dots while the answer is already there.
• typing animates text in. It only works on a string, so a contentRender that returns Markdown as a node shows the text at once.
• Keep streaming on until the stream ends. Without it, onTypingComplete fires every time the animation catches up with the text received so far, which can be many times for one reply. With it, the callback fires once.
• keepPrefix (on by default) keeps the part of the text that did not change on screen when content is replaced, so a growing string animates only its new end.

• Give every item a stable key. Use your message id, not the array index, so each bubble keeps its own state when messages are added or removed.
• Do not name your own roles system or divider. Those two render Bubble.System and Bubble.Divider, whatever props you give them. Pick another name for a custom bubble.
• A role can be a function of the item, so one role renders a different footer for a message that failed.
• With useXChat, pass each message's status on the item. It reaches every slot function and contentRender through info.

• autoScroll (on by default) follows new messages while the reader is at the bottom, and leaves the view alone once they scroll up to read.
• To jump somewhere yourself, take a ref and call scrollTo({ top: 'bottom' }) or scrollTo({ key }). A “scroll to latest” button is the usual place for it.

• Keep the editing state in your own state, set editable={editingKey === item.key}, and set it back in both onEditConfirm and onEditCancel. Otherwise the editor stays open after confirm.
• Only a string content can be edited. A node or an object throws when the editor opens.
• onEditConfirm hands you plain text with line breaks. Treat it like any user input before you send or render it.

• On Bubble.List, classNames styles every bubble at once, and a role or an item overrides it. Put per-sender styling in the role map.