Chat

The Chat widget is a container for displaying a sequence of Message widgets. It provides a simple API for building chat-style interfaces and ensures that new messages are automatically scrolled into view.

Chat does not render messages itself — each message is responsible for its own content and layout. The role of Chat is to manage message order, visibility, and scrolling behavior.

Live Demo

You can try the Chat widget directly in this interactive example:

🚀 Load interactive demo Hover to start

🛠️ Source code ⛅ Mercury Cloud

Basic Usage

Create a chat container and add messages to it:

import mercury as mr

chat = mr.Chat()

chat.add(mr.Message(markdown="Hello 👋", role="assistant"))
chat.add(mr.Message(markdown="Hi!", role="user"))

Messages are displayed in the order they are added.

Chat + Message Together

Chat is designed to work together with the Message widget.

Each Message:

• renders its own content (Markdown, HTML, plots, tables, etc.)
• controls avatar, emoji, and formatting

Chat:

• stacks messages vertically
• shows a placeholder when empty
• scrolls automatically when new messages appear

Auto-Scrolling Behavior ⭐

One of the key features of Chat is automatic scrolling.

Whenever a new message is added:

• the chat scrolls to the most recent message
• scrolling waits briefly to allow large outputs (plots, images) to finish rendering

This makes Chat suitable for:

• conversational UIs
• LLM chat apps
• data exploration assistants
• streaming outputs

Note

Chat itself does not create a scrollbar. Scrolling happens in the surrounding Mercury application container.

Displaying Rich Outputs in Chat

Because Message is a generic output container, Chat can display any output supported by Mercury.

Chat with Charts

import matplotlib.pyplot as plt
import mercury as mr

chat = mr.Chat()

msg = mr.Message(markdown="Here is the chart:")
chat.add(msg)

with msg:
    plt.plot([1, 2, 3], [2, 1, 4])
    plt.title("Example plot")
    plt.show()

The plot is rendered inside the chat message, and the chat scrolls automatically.

Chat with DataFrames

import pandas as pd
import mercury as mr

chat = mr.Chat()

df = pd.DataFrame({
    "product": ["A", "B", "C"],
    "sales": [120, 90, 150]
})

msg = mr.Message(markdown="Sales data:")
chat.add(msg)

with msg:
    display(df)

This pattern is ideal for conversational data analysis.

Streaming Responses

A common pattern is to add an empty message first, then update it incrementally:

msg = mr.Message()
chat.add(msg)

msg.append_markdown("Thinking")
msg.append_markdown("...")
msg.append_markdown("\n\nAnswer ready!")

The chat scrolls as content grows, making it ideal for LLM streaming responses.

Chat Props

placeholder

type: string

Text displayed when the chat contains no messages.

Default:

💬 No messages yet. Start the conversation!

---

scroll_container_selector

type: string

CSS selector used to locate the preferred scrollable container.

Default:

#mercury-main-panel, .mercury-main-panel

This is usually the main content area of a Mercury App.

Note

You usually do not need to change this value unless you are embedding Chat inside a custom layout.

---

Chat Methods

add()

Add a Message to the chat and scroll to it.

chat.add(mr.Message(markdown="New message"))

---

clear()

Remove all messages and show the placeholder.

chat.clear()

---

What Chat Does Not Do

To avoid confusion, it is important to note that Chat:

• does not format messages
• does not limit message types
• does not manage user input
• does not impose a conversation structure

It is a lightweight container, not a full chat application framework.

---

Notes

• Chat manages ordering and scrolling only
• All rendering logic lives in the Message widget
• Auto-scrolling is resilient to large outputs (plots, images)
• Internally, scrolling is implemented using a small frontend helper widget