Skip to contents

shadshiny ships two levels of chat. The chat kit (shad_bubble(), shad_message(), shad_message_scroller(), shad_attachment(), shad_marker()) is a set of transcript primitives you compose yourself – see Gallery: chat. This guide is about the level above it: shad_chat_ui() / shad_chat_server(), a Shiny module that gives you the whole thing – scroller, composer, streaming, Markdown – for two calls.

The whole app

library(shiny)
library(shadshiny)

ui <- page_shad(
  div(style = "max-width:44rem;margin:0 auto;",
    shad_chat_ui("chat", placeholder = "Ask me anything...")
  )
)

server <- function(input, output, session) {
  shad_chat_server("chat", handler = function(user_text, history) {
    paste("You said:", user_text)
  })
}

shinyApp(ui, server)

It is an ordinary Shiny module, so the id is the only wiring: pass the same string to both halves. Nesting it inside another module works without thought – all the namespacing is internal.

The UI half

shad_chat_ui(
  "chat",
  placeholder = "Message...",
  height      = "60vh",
  send_label  = "Send",
  welcome     = shad_empty(
    title       = "Start the conversation",
    description = "Type a message below and press Enter."
  )
)

welcome renders while the transcript is empty and disappears on the first message. The composer is a shad_textarea() that grows with the content; Enter sends, Shift+Enter inserts a newline. The scroller sticks to the bottom while streaming unless the user has scrolled up – then it stays put, which is what you want when someone is reading back.

The handler

handler is function(user_text, history), where history is the transcript so far as a list of list(role, content) with role being "user" or "assistant". It may return any of three things.

A string – the complete reply, rendered at once:

function(user_text, history) {
  paste("You said:", user_text)
}

A chunk function – a function of no arguments returning the next piece of text, or NULL when done. This is the simple streaming protocol:

function(user_text, history) {
  words <- strsplit("A reply that arrives one word at a time.", " ")[[1]]
  i <- 0L
  function() {
    i <<- i + 1L
    if (i > length(words)) NULL else paste0(if (i > 1) " ", words[i])
  }
}

A coro generator – drained the same way, which is what makes ellmer a one-liner. Live provider integrations like this one are experimental: they depend on the provider’s package and API, and may change before a stable 1.0 release.

chat <- ellmer::chat_openai(model = "gpt-4o-mini")

shad_chat_server("chat", handler = function(user_text, history) {
  chat$stream(user_text)     # a coro generator; streams straight through
})

That chat object keeps its own conversation state, so you can ignore history there. Use history when you’re calling an API yourself and need to send the prior turns along.

Chunks are pulled on a short timer and appended to the partial reply, so the transcript renders progressively. Because the pump runs in the Shiny event loop, a chunk function that blocks blocks the whole session – never Sys.sleep() inside one, and never do a synchronous HTTP call per chunk.

The returned object

server <- function(input, output, session) {
  chat <- shad_chat_server("chat", handler = my_handler)

  observeEvent(input$clear, chat$clear())

  observeEvent(input$greet, {
    chat$append("assistant", "Hi! What can I help with?")
  })

  output$n <- renderText(sprintf("%d messages", length(chat$messages())))
}
Member Is
messages() A reactive holding the transcript: a list of list(role, content).
clear() Empty the transcript and drop any in-flight reply.
busy() A read-only reactive that is TRUE while a reply is streaming.
cancel() Stop an in-flight reply without clearing existing messages.
append(role, content) Push a message in directly, without going through the handler.

append() is how you seed an opening line, replay a saved conversation, or inject a system notice mid-thread.

Utility elements for transcripts

Use shad_code_block() for escaped fenced source shown in a transcript or tool result, and shad_shimmer() for a temporary loading label. The latter remains ordinary readable text when inactive or when reduced motion is requested.

~{r} shad_shimmer(“Thinking…”, active = TRUE) shad_code_block( ‘answer <- model$complete(prompt)’, language = “r”, filename = “tool.R”, copy = TRUE ) ~

Markdown

Assistant replies render as Markdown by default – bold, italics, links, code spans, and fenced code blocks. Raw HTML inside that Markdown is escaped. User messages are also escaped and rendered literally, so neither side can inject markup into your page by default.

Turn it off with markdown = FALSE and assistant text is escaped too:

shad_chat_server("chat", handler = my_handler, markdown = FALSE)

For trusted, developer-controlled replies only, raw HTML can be enabled with allow_html = TRUE. Never enable it for user or LLM output: model output is untrusted input even when Markdown rendering is useful.

If a streaming generator fails, the server emits a warning for operators, cancels the stream, and shows a fixed safe error message. The underlying error is never copied into the transcript.

Try it

shad_run_example("08-llm-chat")

Runs offline against a fake token-streaming model, with the experimental ellmer swap commented in the source.

See also

  • Gallery: chat – the primitives, if you want to build a transcript by hand instead.