Message list
A log of messages: runs by author and day, a new-messages divider, reactions, threads, states, anchored at the bottom.
import { MessageList, MessageItem, buildConversationRows, conversationFirstUnread, toggleConversationReaction } from "@forgeron/ui";The export job failed twice last night.
Logs are in #OPS-40, look for
timeout.Found it: the webhook is sent twice. I will add an idempotency key.
Great, ship it before noon? (edited)
Karim joined the channel
New messages
On it. Review welcome.
import {
MessageList,
RichComposer,
toggleConversationReaction,
type ConversationMessage,
} from "@forgeron/ui";
import { useState } from "react";
const lea = { id: "lea", name: "Léa Martin" };
const karim = { id: "karim", name: "Karim Aziz" };
const me = { id: "me", name: "You" };
const start: ConversationMessage[] = [
{
id: "1",
at: "2026-11-18T16:40:00Z",
author: karim,
body: "The export job failed twice last night.",
},
{
id: "2",
at: "2026-11-18T16:41:00Z",
author: karim,
body: "Logs are in #[OPS-40](ops-40), look for `timeout`.",
},
{
id: "3",
at: "2026-11-19T08:55:00Z",
author: lea,
body: "Found it: the **webhook** is sent twice. I will add an idempotency key.",
reactions: [{ emoji: "👍", users: [karim] }],
replyCount: 2,
lastReplyAt: "2026-11-19T09:10:00Z",
},
{
id: "4",
at: "2026-11-19T09:02:00Z",
author: me,
body: "Great, ship it before noon?",
edited: true,
},
{ id: "5", at: "2026-11-19T09:20:00Z", kind: "system", body: "Karim joined the channel" },
{
id: "6",
at: "2026-11-19T09:22:00Z",
author: karim,
body: "On it. Review welcome.",
replyTo: { id: "3", author: "Léa Martin", text: "Found it: the webhook is sent twice." },
},
];
export default function Default() {
const [messages, setMessages] = useState(start);
const react = (id: string, emoji: string) =>
setMessages((all) =>
all.map((m) =>
m.id === id
? { ...m, reactions: toggleConversationReaction(m.reactions ?? [], emoji, me) }
: m,
),
);
return (
<div
style={{
display: "flex",
flexDirection: "column",
height: 460,
width: "100%",
maxWidth: 680,
border: "1px solid var(--line-strong)",
}}
>
<MessageList
messages={messages}
currentUserId="me"
unreadFromId="6"
now="2026-11-19T12:00:00Z"
timeZone="UTC"
onReact={react}
onReply={() => {}}
onOpenThread={() => {}}
onEdit={() => {}}
onDelete={(m) =>
setMessages((all) => all.map((x) => (x.id === m.id ? { ...x, deleted: true } : x)))
}
/>
<RichComposer
placeholder="Write to #ops…"
onSend={({ text }) =>
setMessages((all) => [
...all,
{ id: `n${all.length}`, at: new Date().toISOString(), author: me, body: text },
])
}
/>
</div>
);
}My invoice shows the wrong VAT number.
Screenshot attached.
- invoice-214.pdf
- upload.png
Thanks, checking now.
Sending…I can fix it today.
This message was deleted.
Ticket assigned to Jo Bernard
import { MessageList, type ConversationMessage } from "@forgeron/ui";
const sam = { id: "sam", name: "Sam Roche", role: "Customer" };
const agent = { id: "agent", name: "Jo Bernard", role: "Support" };
const messages: ConversationMessage[] = [
{
id: "1",
at: "2026-11-19T09:00:00Z",
author: sam,
body: "My invoice shows the wrong VAT number.",
},
{
id: "2",
at: "2026-11-19T09:02:00Z",
author: sam,
body: "Screenshot attached.",
attachments: [
{ id: "a", name: "invoice-214.pdf", size: 238000, url: "#" },
{ id: "b", name: "upload.png", size: 1_800_000, progress: 0.6 },
],
},
{
id: "3",
at: "2026-11-19T09:05:00Z",
author: agent,
body: "Thanks, checking now.",
status: "sending",
},
{
id: "4",
at: "2026-11-19T09:06:00Z",
author: agent,
body: "I can fix it today.",
status: "failed",
},
{ id: "5", at: "2026-11-19T09:07:00Z", author: sam, body: "Removed.", deleted: true },
{ id: "6", at: "2026-11-19T09:10:00Z", kind: "system", body: "Ticket assigned to Jo Bernard" },
];
export default function States() {
return (
<div
style={{ height: 420, width: "100%", maxWidth: 680, border: "1px solid var(--line-strong)" }}
>
<MessageList
messages={messages}
currentUserId="agent"
now="2026-11-19T12:00:00Z"
timeZone="UTC"
onRetry={() => {}}
onDiscard={() => {}}
/>
</div>
);
}Message 1: scroll up, then receive one.
Message 2: scroll up, then receive one.
Message 3: scroll up, then receive one.
Message 4: scroll up, then receive one.
Message 5: scroll up, then receive one.
Message 6: scroll up, then receive one.
Message 7: scroll up, then receive one.
Message 8: scroll up, then receive one.
Message 9: scroll up, then receive one.
Message 10: scroll up, then receive one.
Message 11: scroll up, then receive one.
Message 12: scroll up, then receive one.
Message 13: scroll up, then receive one.
Message 14: scroll up, then receive one.
Message 15: scroll up, then receive one.
Message 16: scroll up, then receive one.
Message 17: scroll up, then receive one.
Message 18: scroll up, then receive one.
Message 19: scroll up, then receive one.
Message 20: scroll up, then receive one.
Message 21: scroll up, then receive one.
Message 22: scroll up, then receive one.
Message 23: scroll up, then receive one.
Message 24: scroll up, then receive one.
Karim is typing…
import { Button, MessageList, TypingIndicator, type ConversationMessage } from "@forgeron/ui";
import { useState } from "react";
const lea = { id: "lea", name: "Léa Martin" };
const seed = Array.from({ length: 24 }, (_, i): ConversationMessage => ({
id: `m${i}`,
at: new Date(Date.UTC(2026, 10, 19, 8, i * 7)).toISOString(),
author: i % 3 === 0 ? lea : { id: "karim", name: "Karim Aziz" },
body: `Message ${i + 1}: scroll up, then receive one.`,
}));
export default function Live() {
const [messages, setMessages] = useState(seed);
const [older, setOlder] = useState(0);
return (
<div style={{ width: "100%", maxWidth: 680 }}>
<div style={{ display: "flex", gap: 8, marginBottom: 8 }}>
<Button
size="sm"
onClick={() =>
setMessages((all) => [
...all,
{
id: `n${all.length}`,
at: new Date().toISOString(),
author: lea,
body: "A new message arrives.",
},
])
}
>
Receive a message
</Button>
<Button
size="sm"
onClick={() => {
setOlder((n) => n + 1);
setMessages((all) => [
{
id: `old${older}`,
at: new Date(Date.UTC(2026, 10, 18, 9, older)).toISOString(),
author: lea,
body: `An older message ${older + 1}, added on top.`,
},
...all,
]);
}}
>
Load an older one
</Button>
</div>
<div
style={{
display: "flex",
flexDirection: "column",
height: 360,
border: "1px solid var(--line-strong)",
}}
>
<MessageList
messages={messages}
currentUserId="me"
now="2026-11-19T12:00:00Z"
timeZone="UTC"
/>
<TypingIndicator names={["Karim"]} />
</div>
</div>
);
}API → Props
| Prop | Type | Default | Description |
|---|---|---|---|
messages | ConversationMessage[] | — | Oldest first: { id, at, author, body, kind?, edited?, deleted?, status?, replyTo?, reactions?, attachments?, replyCount?, lastReplyAt? }. A string body reads **bold**, *italic*, `code`, links and @[Name](id) mentions; no HTML. |
currentUserId | string | — | Whose messages are yours: edit and delete are offered on them, they are marked. |
onReact | (messageId, emoji) => void | — | An emoji pressed or chosen on a message. The caller adds or removes it (toggleConversationReaction). |
onReply / onOpenThread | (message) => void | — | Reply (the caller fills the composer's reply bar); open the thread of a message. |
onEdit / onDelete / onCopy | (message) => void | — | Edit and delete are offered on your own messages; copy uses the clipboard by default. |
onRetry / onDiscard | (message) => void | — | On a message whose status is failed. |
actions / onAction | (message) => ActionMenuEntry[]; (id, message) => void | — | More rows in each message's menu. onAction also hears the usual ids (reply, thread, copy, edit, delete). |
onMentionClick | ({ char, id, label }) => void | — | Mentions become buttons. |
timeZone | string | — | IANA zone for days and times; the device's by default. |
unreadFromId | string | null | — | The divider goes before this message. conversationFirstUnread finds it. |
onMarkRead | () => void | — | Once, when the person reaches the bottom while the divider is shown. |
stickToBottom | boolean | true | Follow new messages while at the bottom. Scrolled up, a Jump to latest button counts what came; older messages added on top keep your place. |
onReachTop / loadingOlder | () => void; boolean | — | Load older messages when the top is reached. |
gapMinutes / now / label / newMessagesLabel / empty | number; string; string; string; string | — | Silence that starts a new run (5), the clock for Today, and the words. |
className | string | — | Extra classes. |