An icon action for the message bar - thumbs up/down, regenerate, share. Icon-only with the accessible name on label (also the tooltip). Pass any phx-* binding through.

<Chat.action_button icon="hero-hand-thumb-up" label="Good response" phx-click="feedback" phx-value-vote="up" />

Attributes

• icon (:string) (required) - heroicon name.
• label (:string) (required) - accessible name, also shown as the tooltip.
• class (:any) - Defaults to nil.
• Global attributes are accepted.

An error notice with an optional retry button.

<Chat.chat_error on_retry="retry">Something went wrong.</Chat.chat_error>

Attributes

• on_retry (:string) - Defaults to nil.
• retry_label (:string) - Defaults to "Retry".
• class (:any) - Defaults to nil.

Slots

• inner_block (required)

A single message bubble.

Default markup, or replace it entirely — the class is appended last so your utilities win, and the :inner_block is yours to fill.

Attributes

• role (:string) - Defaults to "assistant". Must be one of "user", "assistant", or "system".
• class (:any) - Defaults to nil.
• Global attributes are accepted.

Slots

• avatar - optional leading avatar/icon.
• actions - an action bar rendered below the message, outside the bubble - message_actions/1. Works on any role: copy/edit under a user message, copy/feedback/regenerate under an assistant one.
• inner_block (required)

A scrollable conversation thread. Composition-first: drop chat_message/1, streaming_text/1, or your own markup inside.

Opens scrolled to the latest message. When older history is inserted above (pagination), the reader's position is preserved - give thread rows stable ids (or render them from a LiveView stream) so patches reuse the DOM nodes; without ids, LiveView rebuilds the siblings and the browser resets the scroll.

<Chat.conversation>
  <Chat.chat_message :for={msg <- @messages} role={msg.role}>{msg.text}</Chat.chat_message>
  <:footer>
    <Chat.prompt_input phx-submit="send" loading={@streaming?} />
  </:footer>
</Chat.conversation>

Attributes

• id (:string) - defaults to a generated id so multiple threads can coexist.
• variant (:string) - plain is the AI convention (ChatGPT/Claude): assistant text sits on the surface, only the user gets a bubble. bubbles puts both sides in bubbles (messenger style). Defaults to "plain". Must be one of "plain", or "bubbles".
• class (:any) - Defaults to nil.
• Global attributes are accepted.

Slots

• inner_block (required)
• footer - pinned below the scroll area, e.g. a prompt_input.

A copy-to-clipboard button (via the PetalCopy hook). Shows brief feedback - the text flips to "Copied!", or in icon mode the clipboard swaps to a check. Requires a unique id.

Attributes

• id (:string) (required)
• text (:string) (required) - the text to copy.
• label (:string) - Defaults to "Copy".
• icon (:boolean) - icon-only (clipboard -> check feedback). Defaults to false.
• class (:any) - Defaults to nil.

Renders markdown as sanitized, syntax-highlighted HTML (via MDEx). Use it for committed assistant messages so headings, lists, tables and code blocks render properly:

<Chat.chat_message role="assistant"><Chat.markdown content={msg.text} /></Chat.chat_message>

Output is sanitized server-side — model text is never rendered as live markup.

Attributes

• content (:string) (required)
• id (:string) - pass a unique id to enable per-code-block copy buttons. Defaults to nil.
• class (:any) - Defaults to nil.

An inline conversation marker - a system note, a status row, or a labelled separator between sections of the thread.

<Chat.marker icon="hero-magnifying-glass">Searched the web</Chat.marker>
<Chat.marker variant="separator">Today</Chat.marker>
<Chat.marker variant="border" icon="hero-check-circle">Context compacted</Chat.marker>
<Chat.marker loading>Thinking...</Chat.marker>

While loading it shows a small spinner and announces as a live status region. For the shimmering streaming-status treatment, compose the existing PetalComponents.TextAnimation.shimmer_text/1 inside:

<Chat.marker loading><.shimmer_text>Running the numbers...</.shimmer_text></Chat.marker>

Attributes

• variant (:string) - inline note, centred labelled separator, or a full-width bordered row. Defaults to "inline". Must be one of "inline", "separator", or "border".
• icon (:string) - heroicon name rendered before the text. Defaults to nil.
• loading (:boolean) - spinner + role=status for in-progress work. Defaults to false.
• class (:any) - Defaults to nil.
• Global attributes are accepted.

Slots

• inner_block (required)

A row of actions under a message - the copy / feedback / regenerate bar. Compose with copy_button/1, action_button/1, or your own phx-click buttons using the pc-chat__action class.

<Chat.message_actions>
  <Chat.copy_button id={"copy-#{@id}"} text={@text} icon />
  <Chat.action_button icon="hero-hand-thumb-up" label="Good response" phx-click="feedback" phx-value-vote="up" />
  <Chat.action_button icon="hero-arrow-path" label="Regenerate" phx-click="regenerate" />
</Chat.message_actions>

visible="hover" fades the bar in when the message row is hovered or focused (ChatGPT-style density for long threads). Touch devices have no hover, so there the bar always shows.

Attributes

• visible (:string) - hover reveals the bar on message-row hover/focus; always shows on touch. Defaults to "always". Must be one of "always", or "hover".
• class (:any) - Defaults to nil.

Slots

• inner_block (required)

The composer. Wraps a form; pass phx-submit (and optionally phx-change) through the global attrs.

<Chat.prompt_input phx-submit="send" phx-change="draft" value={@draft} loading={@streaming?} on_stop="stop" />

While loading, the input stays editable (so you can draft your next message) and the send button becomes a stop button that pushes on_stop — wire it to cancel your generation task.

Attributes

• id (:string) - defaults to a generated id so multiple composers can coexist.
• name (:string) - Defaults to "prompt".
• value (:string) - initial textarea value. The field is uncontrolled after mount (phx-update=ignore, so keystrokes never re-render and lose focus); set it later - edit, quote, clear - by pushing a pc-chat-set-input event (%{value: text}, optional %{id: composer_id}) to the PetalChatComposer hook. Defaults to "".
• placeholder (:string) - Defaults to "Send a message...".
• aria_label (:string) - accessible label for the textarea. Defaults to "Message".
• loading (:boolean) - Defaults to false.
• on_stop (:string) - event pushed when the stop button is clicked while loading. Defaults to nil.
• submit_label (:string) - text for the send button; the default is the arrow-up icon convention. Defaults to nil.
• editing (:boolean) - show the edit-mode banner above the field (set while editing a past message). Defaults to false.
• edit_label (:string) - label shown in the edit banner. Defaults to "Editing message".
• on_cancel_edit (:string) - event pushed when the edit banner's cancel (X) is clicked. Defaults to nil.
• class (:any) - Defaults to nil.
• Global attributes are accepted. Supports all globals plus: ["phx-submit", "phx-change", "phx-target"].

Slots

• actions - extra controls left of the send button.

A collapsible "thinking" / reasoning block for reasoning-model output. Native <details>, so no JS.

<Chat.reasoning>Chain of thought here...</Chat.reasoning>
<Chat.reasoning label="Thought for 3s" open>...</Chat.reasoning>

Attributes

• label (:string) - Defaults to "Reasoning".
• open (:boolean) - Defaults to false.
• class (:any) - Defaults to nil.

Slots

• inner_block (required)

Markdown with inline widget directives ("MDX for Phoenix").

The model can drop a widget mid-prose with a fenced block tagged ```widget:<name> containing JSON args. Everything else renders as normal markdown (normal code fences like ```elixir are untouched). You supply a render_widget function that maps a name + args to a rendered component:

<Chat.rich_text
  content={@text}
  render_widget={fn
    "weather", args -> ~H"<.weather_card city={args["city"]} .../>"
    _, _ -> nil
  end}
/>

Example model output:

Here's the forecast:

```widget:weather
{"city": "Paris"}
```

Pack an umbrella.

Attributes

• content (:string) (required)

• render_widget (:any) - fn(name :: String.t(), args :: map) -> rendered | nil. Defaults to nil.

• class (:any) - Defaults to nil.

Token-by-token streaming output, driven by the PetalChatStream JS hook.

Render this in the in-progress assistant bubble. The parent LiveView pushes each delta to it:

socket = push_event(socket, "pc-chat-token", %{id: "answer", text: delta})

<Chat.streaming_text id="answer" />

Until the first token lands it shows a typing indicator; on the first token it swaps to live text with a blinking caret. The element owns its own DOM (phx-update="ignore"), so no re-render clobbers the streamed text.

Attributes

• id (:string) (required)
• event (:string) - push_event name the hook listens for. Defaults to "pc-chat-token".
• format (:string) - "text" appends raw token deltas; "markdown" replaces innerHTML with rendered HTML you push (see to_html/1). Defaults to "text". Must be one of "text", or "markdown".
• class (:any) - Defaults to nil.

Clickable prompt-starter chips for an empty state. Each pushes on_select with phx-value-prompt set to the suggestion.

<Chat.suggestions items={["Summarise this", "Write tests"]} on_select="suggest" />

Attributes

• items (:list) (required)
• on_select (:string) - event pushed with phx-value-prompt. Defaults to "suggestion".
• class (:any) - Defaults to nil.

Render markdown to sanitized, syntax-highlighted HTML using the same engine the markdown/1 component uses. Use it to live-stream markdown: throttle calls on your growing buffer and push_event the result to a format="markdown" streaming_text/1:

socket = push_event(socket, "pc-chat-token", %{id: "answer", html: PetalComponents.Chat.to_html(buffer)})

A tool-call card — the chrome around a generative-UI widget.

This is the "AI Elements" pattern done LiveView-native: the model emits a structured tool call (function calling), you map the tool name to one of your registered Phoenix components, and render it inside this card. The widget is a real LiveView component — it can have its own phx-click, forms, streams.

<Chat.tool_call name="get_weather" status={:complete}>
  <.weather_card city={@args["city"]} temp={@result.temp} />
</Chat.tool_call>

status drives the header affordance: :running shows a spinner, :complete a check, :error a warning.

Attributes

• name (:string) (required)
• status (:atom) - Defaults to :complete. Must be one of :running, :complete, or :error.
• label (:string) - human label; defaults to the tool name. Defaults to nil.
• class (:any) - Defaults to nil.

Slots

• inner_block - the rendered widget / tool result.