Preserve send‑order of content and elements inside a single cl.Message Summary

[kawashishu]

trafficstars

❓ Feature request: Preserve send‑order of content and elements inside a single cl.Message

Summary

A cl.Message always renders its content (markdown) above its inline elements[], no matter the order in which each part was added or updated. This prevents flows like “chart → streamed explanation → table” inside one bubble. The request: allow the display order to follow the order of sends/updates (or provide a simple way to choose the order).

---

🔬 Minimal reproducible example

import asyncio
from pathlib import Path
import chainlit as cl
import pandas as pd
@cl.on_message
async def handler(_: cl.Message):
# 0️⃣ create the container
msg = cl.Message(content="")
await msg.send()
# 1️⃣ element FIRST  (image)
img = cl.Image(path="sample.png", name="demo-plot", display="inline")
msg.elements.append(img)
await msg.update()

# 2️⃣ streamed text SECOND
text = "The chart above shows....."
for tok in text.split():
    await msg.stream_token(tok)

await msg.send()

Observed UI

(markdown text …)
<inline image>

Expected UI

<inline image>
(markdown text … streaming)

---

✔️ Proposed API options

Option	Description	Back‑compat?
Message(render_order="send")	Track a timestamp per part (content, each element) and sort ascending.	✅ Default keeps current behaviour ("fixed").
Element(position=0‑n)	Allow explicit indices; lowest index shows first.	✅ Ignored if missing.
elements_position="above" / "below"	Quick switch for common need: draw elements above content.	✅ Default "below".

Any solution that lets devs control vertical order would be valuable.

---

💻 Environment

Chainlit : 2.5.5
Python   : 3.11.8
OS       : Ubuntu 22.04
Browser  : Chrome 125

---

📣 Why this matters

• Real‑time dashboards (show chart first, then live commentary).

• Educational bots that reveal text after media clues.

• Agents that display tool output before justification.

Currently we must split content into separate messages or steps, which breaks the single‑bubble UX and complicates history.

Thanks for considering! Happy to test or help with docs if the maintainers can outline a preferred approach.