ui.Chat

ui.Chat(id, *, messages=(), on_error='auto', tokenizer=None)

Create a chat interface.

A UI component for building conversational interfaces. With it, end users can submit messages, which will cause a .on_user_submit() callback to run. That callback gets passed the user input message, which can be used to generate a response. The response can then be appended to the chat using .append_message() or .append_message_stream().

Here's a rough outline for how to implement a Chat:

from shiny.express import ui

# Create and display chat instance
chat = ui.Chat(id="my_chat")
chat.ui()


# Define a callback to run when the user submits a message
@chat.on_user_submit
async def handle_user_input(user_input: str):
    # Create a response message stream
    response = await my_model.generate_response(user_input, stream=True)
    # Append the response into the chat
    await chat.append_message_stream(response)

In the outline above, my_model.generate_response() is a placeholder for the function that generates a response based on the chat's messages. This function will look different depending on the model you're using, but it will generally involve passing the messages to the model and getting a response back. Also, you'll typically have a choice to stream=True the response generation, and in that case, you'll use .append_message_stream() instead of .append_message() to append the response to the chat. Streaming is preferrable when available since it allows for more responsive and scalable chat interfaces.

It is also highly recommended to use a package like chatlas to generate responses, especially when responses should be aware of the chat history, support tool calls, etc. See this article to learn more.

Thinking display

When a model produces reasoning or “thinking” tokens, shinychat renders them in a collapsible panel above the response. The panel streams the model’s reasoning in real time, then auto-collapses when the response begins.

Two paths are supported:

  1. chatlas ContentThinking objects. Models with a structured thinking API (e.g., Claude with extended thinking) emit ContentThinking objects during streaming. shinychat detects these and routes them to the thinking panel automatically.

  2. Raw <thinking> tags. Many open-source and local models (DeepSeek, QwQ, Qwen, etc.) emit <thinking>...</thinking> tags in their markdown output. shinychat detects these tags during streaming and renders the enclosed text in the thinking panel with no extra configuration.

Topic labels: You can get labeled sub-sections within the thinking panel by asking the model to emit <topic>...</topic> tags in its reasoning. These show up as section headings inside the panel, and the current topic appears in the collapsed header as a live status indicator.

To use topic labels, add something like this to your system prompt::

When thinking through a problem, wrap brief topic labels in <topic> tags
to indicate what you're currently reasoning about. For example:
<topic>parsing the input</topic>

Topic labels are optional. Without them, the thinking panel still works – it just won’t have sub-section headings.

Parameters

id :

A unique identifier for the chat session. In Shiny Core, make sure this id matches a corresponding chat_ui call in the UI.

messages :

Deprecated. Use chat.ui(messages=...) instead.

on_error :

How to handle errors that occur in response to user input. When "unhandled", the app will stop running when an error occurs. Otherwise, a notification is displayed to the user and the app continues to run. * "auto": Sanitize the error message if the app is set to sanitize errors, otherwise display the actual error message. * "actual": Display the actual error message to the user. * "sanitize": Sanitize the error message before displaying it to the user. * "unhandled": Do not display any error message to the user.

tokenizer :

Deprecated. Token counting and message trimming features will be removed in a future version.

Examples

#| '!! shinylive warning !!': |
#|   shinylive does not work in self-contained HTML documents.
#|   Please set `embed-resources: false` in your metadata.
#| standalone: true
#| components: [editor, viewer]
#| layout: vertical
#| viewerHeight: 400

## file: app.py
from shiny import App, ui

app_ui = ui.page_fillable(
    ui.panel_title("Hello Shiny Chat"),
    ui.chat_ui("chat"),
    ui.chat_ui(
        "chat",
        messages=["""
Hi! This is a simple Shiny `Chat` UI. Enter a message below and I will
simply repeat it back to you.

To learn more about chatbots and how to build them with Shiny, check out
[the documentation](https://shiny.posit.co/py/docs/genai-chatbots.html).
"""],
    ),
    fillable_mobile=True,
)


def server(input, output, session):
    chat = ui.Chat(id="chat")

    # Define a callback to run when the user submits a message
    @chat.on_user_submit
    async def handle_user_input(user_input: str):
        # Append a response to the chat
        await chat.append_message(f"You said: {user_input}")


app = App(app_ui, server)


## file: requirements.txt
shiny


## file: _template.json
{
  "type": "app",
  "id": "chat-hello",
  "title": "Hello Shiny Chat",
  "next_steps": [
    "Run the app with `shiny run app.py`."
  ]
}

Attributes

Name Description
latest_message_stream React to changes in the latest message stream.

Methods

Name Description
append_message Append a message to the chat.
append_message_stream Append a message as a stream of message chunks.
clear_messages Clear all chat messages.
destroy Destroy the chat instance.
enable_bookmarking Enable bookmarking for the chat instance.
message_stream_context Message stream context manager.
messages Reactively read chat messages
on_user_submit Define a function to invoke when user input is submitted.
set_greeting Set or clear the chat greeting.
set_user_message Deprecated. Use update_user_input(value=value) instead.
transform_assistant_response Deprecated. Assistant response transformation features will be removed in a future version.
transform_user_input Deprecated. User input transformation features will be removed in a future version.
update_user_input Update the user input.
user_input Reactively read the user’s message.

append_message

ui.Chat.append_message(message, *, icon=None)

Append a message to the chat.

Parameters

message : Any

A given message can be one of the following: * A string, which is interpreted as markdown and rendered to HTML on the client. * To prevent interpreting as markdown, mark the string as HTML. * A UI element (specifically, a TagChild). * This includes TagList, which take UI elements (including strings) as children. In this case, strings are still interpreted as markdown as long as they’re not inside HTML. * A dictionary with content and role keys. The content key can contain content as described above, and the role key can be “assistant” or “user”. * More generally, any type registered with shinychat.message_content. NOTE: content may include specially formatted input suggestion links (see note below).

icon : HTML | Tag | TagList | None = None

An optional icon to display next to the message, currently only used for assistant messages. The icon can be any HTML element (e.g., an img tag) or a string of HTML.

Note

NoteInput suggestions

Input suggestions are special links that send text to the user input box when clicked (or accessed via keyboard). They can be created in the following ways:

  • <span class='suggestion'>Suggestion text</span>: An inline text link that places ‘Suggestion text’ in the user input box when clicked.
  • <img data-suggestion='Suggestion text' src='image.jpg'>: An image link with the same functionality as above.
  • <span data-suggestion='Suggestion text'>Actual text</span>: An inline text link that places ‘Suggestion text’ in the user input box when clicked.

A suggestion can also be submitted automatically by doing one of the following:

  • Adding a submit CSS class or a data-suggestion-submit="true" attribute to the suggestion element.
  • Holding the Ctrl/Cmd key while clicking the suggestion link.

Note that a user may also opt-out of submitting a suggestion by holding the Alt/Option key while clicking the suggestion link.

A markdown list (<ul> or <ol>) in which every item contains a single suggestion element is automatically rendered as a grid of clickable cards instead of inline chips. Each suggestion accepts an optional title attribute (plain text), which becomes the card heading; the suggestion’s body becomes the card description. For ordered lists (<ol>), the list-item number is included in the heading.

NoteStreamed messages

Use .append_message_stream() instead of this method when stream=True (or similar) is specified in model’s completion method.

append_message_stream

ui.Chat.append_message_stream(message, *, icon=None)

Append a message as a stream of message chunks.

Parameters

message : Iterable[Any] | AsyncIterable[Any]

An (async) iterable of message chunks. Each chunk can be one of the following: * A string, which is interpreted as markdown and rendered to HTML on the client. * To prevent interpreting as markdown, mark the string as HTML. * A UI element (specifically, a TagChild). * This includes TagList, which take UI elements (including strings) as children. In this case, strings are still interpreted as markdown as long as they’re not inside HTML. * A dictionary with content and role keys. The content key can contain content as described above, and the role key can be “assistant” or “user”. * More generally, any type registered with shinychat.message_content_chunk. NOTE: content may include specially formatted input suggestion links (see note below).

icon : HTML | Tag | None = None

An optional icon to display next to the message, currently only used for assistant messages. The icon can be any HTML element (e.g., an img tag) or a string of HTML.

Note

Input suggestions are special links that send text to the user input box when
clicked (or accessed via keyboard). They can be created in the following ways:

* `<span class='suggestion'>Suggestion text</span>`: An inline text link that
    places 'Suggestion text' in the user input box when clicked.
* `<img data-suggestion='Suggestion text' src='image.jpg'>`: An image link with
    the same functionality as above.
* `<span data-suggestion='Suggestion text'>Actual text</span>`: An inline text
    link that places 'Suggestion text' in the user input box when clicked.

A suggestion can also be submitted automatically by doing one of the following:

* Adding a `submit` CSS class or a `data-suggestion-submit="true"` attribute to
  the suggestion element.
* Holding the `Ctrl/Cmd` key while clicking the suggestion link.

Note that a user may also opt-out of submitting a suggestion by holding the
`Alt/Option` key while clicking the suggestion link.

A markdown list (`<ul>` or `<ol>`) in which every item contains a single
suggestion element is automatically rendered as a grid of clickable cards instead
of inline chips. Each suggestion accepts an optional `title` attribute (plain
text), which becomes the card heading; the suggestion's body becomes the card
description. For ordered lists (`<ol>`), the list-item number is included in the
heading.
Use this method (over `.append_message()`) when `stream=True` (or similar) is
specified in model's completion method.

Returns

An extended task that represents the streaming task. The .result() method of the task can be called in a reactive context to get the final state of the stream.

clear_messages

ui.Chat.clear_messages(greeting=False)

Clear all chat messages.

Parameters

greeting : bool = False

If True, also clears the greeting in addition to conversation messages. Clearing the greeting causes the {id}_greeting_requested input to fire again (if the chat is visible with no greeting and no messages), enabling a regenerate pattern: clear the greeting, then react to the request to generate a new one via set_greeting.

destroy

ui.Chat.destroy()

Destroy the chat instance.

enable_bookmarking

ui.Chat.enable_bookmarking(client, /, *, bookmark_on='response')

Enable bookmarking for the chat instance.

This method registers on_bookmark and on_restore hooks on session.bookmark (shiny.bookmark.Bookmark) to save/restore chat state on both the Chat and client= instances. In order for this method to actually work correctly, a bookmark_store= must be specified in shiny.App().

Parameters

client : ‘ClientWithState | chatlas.Chat[Any, Any]’

The chat client instance to use for bookmarking. This can be a Chat model provider from chatlas, or more generally, an instance following the ClientWithState protocol.

bookmark_on : Optional[Literal[‘response’]] = 'response'

The event to trigger the bookmarking on. Supported values include: - "response" (the default): a bookmark is triggered when the assistant is done responding. - None: no bookmark is triggered When this method triggers a bookmark, it also updates the URL query string to reflect the bookmarked state.

Raises

: ValueError

If the Shiny App does have bookmarking enabled.

Returns

: CancelCallback

A callback to cancel the bookmarking hooks.

message_stream_context

ui.Chat.message_stream_context()
    Message stream context manager.

    A context manager for appending streaming messages into the chat. This context
    manager can:

    1. Be used in isolation to append a new streaming message to the chat.
        * Compared to `.append_message_stream()` this method is more flexible but
          isn&#x27;t non-blocking by default (i.e., it doesn&#x27;t launch an extended task).
    2. Be nested within itself
        * Nesting is primarily useful for making checkpoints to `.clear()` back
          to (see the example below).
    3. Be used from within a `.append_message_stream()`
        * Useful for inserting additional content from another context into the
          stream (e.g., see the note about tool calls below).

Yields

    :
        A `MessageStream` class instance, which has a method for `.append()`ing
        message content chunks to as well as way to `.clear()` the stream back to
        it's initial state. Note that `.append()` supports the same message content
        types as `.append_message()`.

Example

    ```python
    import asyncio

    from shiny import reactive
    from shiny.express import ui

    chat = ui.Chat(id="my_chat")
    chat.ui()


    @reactive.effect
    async def _():
        async with chat.message_stream_context() as msg:
            await msg.append("Starting stream...

Progress:“) async with chat.message_stream_context() as progress: for x in [0, 50, 100]: await progress.append(f” {x}%“) await asyncio.sleep(1) await progress.clear() await msg.clear() await msg.append(”Completed stream”) ```

Note

    A useful pattern for displaying tool calls in a chatbot is for the tool to
    display using `.message_stream_context()` while the the response generation is
    happening through `.append_message_stream()`. This allows the tool to display
    things like progress updates (or other "ephemeral" content) and optionally
    `.clear()` the stream back to it's initial state when ready to display the
    "final" content.

messages

ui.Chat.messages(format=MISSING, token_limits=None)

Reactively read chat messages

Obtain chat messages within a reactive context.

Parameters

format : ‘MISSING_TYPE | ProviderMessageFormat’ = MISSING

Deprecated. Provider-specific message formatting will be removed in a future version.

token_limits : tuple[int, int] | None = None

Deprecated. Token counting and message trimming features will be removed in a future version.

Note

Messages are listed in the order they were added. As a result, when this method is called in a .on_user_submit() callback (as it most often is), the last message will be the most recent one submitted by the user.

Returns

: tuple[ChatMessage, …]

A tuple of chat messages.

on_user_submit

ui.Chat.on_user_submit(fn=None)

Define a function to invoke when user input is submitted.

Apply this method as a decorator to a function (fn) that should be invoked when the user submits a message. This function can take an optional argument, which will be the user input message.

In many cases, the implementation of fn should also do the following:

  1. Generate a response based on the user input.
  • If the response should be aware of chat history, use a package like chatlas to manage the chat state, or use the .messages() method to get the chat history.
  1. Append that response to the chat component using .append_message() ( or .append_message_stream() if the response is streamed).

Parameters

fn : UserSubmitFunction | None = None

A function to invoke when user input is submitted.

Note

This method creates a reactive effect that only gets invalidated when the user submits a message. Thus, the function fn can read other reactive dependencies, but it will only be re-invoked when the user submits a message.

set_greeting

ui.Chat.set_greeting(greeting)

Set or clear the chat greeting.

A greeting is displayed at the top of the chat before any conversation messages. It can be static content, streaming content from an async iterator, or None to remove an existing greeting.

If the greeting has already been dismissed, calling this method updates the greeting content but does not make it visible again. To show a new greeting after dismissal, first clear the chat with await chat.clear_messages(greeting=True).

Parameters

greeting : ‘str | HTML | Tag | TagList | ChatGreeting | None’

The greeting content. Can be: * None: clears the current greeting entirely (distinct from dismissal). Use this before setting a new greeting when implementing a regenerate pattern. * A markdown string, HTML, Tag, or TagList: displayed as a stand-alone greeting. * A chat_greeting object with options such as dismissible. * A chat_greeting wrapping an AsyncIterable of strings: streams the greeting content chunk-by-chunk.

Notes

When no greeting is set and the chat is visible with no messages, an input named {id}_greeting_requested fires (where {id} is the chat’s ID). Use @reactive.event(input.{id}_greeting_requested) to generate a greeting on demand. This input fires on first load and again after clear_messages is called with greeting=True.

Examples

Static greeting (stand-alone, dismissible by default):

@reactive.effect
async def _():
    await chat.set_greeting("## Welcome!\n\nHow can I help you today?")

Static greeting with custom options:

from shinychat import chat_greeting

@reactive.effect
async def _():
    greeting = chat_greeting(
        "## Welcome!",
        dismissible=True,
    )
    await chat.set_greeting(greeting)

Streaming greeting from an async iterator:

@reactive.effect
async def _():
    async def token_stream():
        for token in ["Hello", " there", "!"]:
            yield token

    await chat.set_greeting(chat_greeting(token_stream()))

LLM-generated greeting using greeting_requested:

import chatlas
from shinychat import Chat, chat_greeting

chat_model = chatlas.ChatOpenAI(model="gpt-4o")
chat = Chat(id="chat")

@reactive.effect
@reactive.event(input.chat_greeting_requested)
async def _():
    response = await chat_model.stream_async(
        "Write a short, friendly welcome message."
    )
    await chat.set_greeting(chat_greeting(response))

Regenerate pattern (clear and re-request):

@reactive.effect
@reactive.event(input.regenerate)
async def _():
    await chat.clear_messages(greeting=True)

# greeting_requested fires again after clear_messages(greeting=True),
# so the LLM-generated greeting handler above will run again.

Clear the greeting (e.g., before setting a new one):

await chat.set_greeting(None)

set_user_message

ui.Chat.set_user_message(value)

Deprecated. Use update_user_input(value=value) instead.

transform_assistant_response

ui.Chat.transform_assistant_response(fn=None)

Deprecated. Assistant response transformation features will be removed in a future version.

transform_user_input

ui.Chat.transform_user_input(fn=None)

Deprecated. User input transformation features will be removed in a future version.

update_user_input

ui.Chat.update_user_input(
    value=None,
    placeholder=None,
    submit=False,
    focus=False,
)

Update the user input.

Parameters

value : str | None = None

The value to set the user input to.

placeholder : str | None = None

The placeholder text for the user input.

submit : bool = False

Whether to automatically submit the text for the user. Requires value.

focus : bool = False

Whether to move focus to the input element. Requires value.

user_input

ui.Chat.user_input()

Reactively read the user's message.

Returns

: str | None

The user input message.

Note

Most users shouldn’t need to use this method directly since the last item in .messages() contains the most recent user input. It can be useful for:

  1. Taking a reactive dependency on the user’s input outside of a .on_user_submit() callback.
  2. Maintaining message state separately from .messages().