Blocks / Message list

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";
/01 → Default
Karim Aziz
The export job failed twice last night.
Logs are in #OPS-40, look for timeout.
Léa Martin
Found it: the webhook is sent twice. I will add an idempotency key.
You
Great, ship it before noon? (edited)
Karim joined the channel
Karim Aziz
On it. Review welcome.
⌘↵ sends
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>
  );
}
/02 → States
Sam RocheCustomer
My invoice shows the wrong VAT number.
Screenshot attached.
Jo BernardSupport
Thanks, checking now.
Sending…
I can fix it today.
Sam RocheCustomer
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>
  );
}
/03 → Live
Léa Martin
Message 1: scroll up, then receive one.
Karim Aziz
Message 2: scroll up, then receive one.
Karim Aziz
Message 3: scroll up, then receive one.
Léa Martin
Message 4: scroll up, then receive one.
Karim Aziz
Message 5: scroll up, then receive one.
Karim Aziz
Message 6: scroll up, then receive one.
Léa Martin
Message 7: scroll up, then receive one.
Karim Aziz
Message 8: scroll up, then receive one.
Karim Aziz
Message 9: scroll up, then receive one.
Léa Martin
Message 10: scroll up, then receive one.
Karim Aziz
Message 11: scroll up, then receive one.
Karim Aziz
Message 12: scroll up, then receive one.
Léa Martin
Message 13: scroll up, then receive one.
Karim Aziz
Message 14: scroll up, then receive one.
Karim Aziz
Message 15: scroll up, then receive one.
Léa Martin
Message 16: scroll up, then receive one.
Karim Aziz
Message 17: scroll up, then receive one.
Karim Aziz
Message 18: scroll up, then receive one.
Léa Martin
Message 19: scroll up, then receive one.
Karim Aziz
Message 20: scroll up, then receive one.
Karim Aziz
Message 21: scroll up, then receive one.
Léa Martin
Message 22: scroll up, then receive one.
Karim Aziz
Message 23: scroll up, then receive one.
Karim Aziz
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
PropTypeDefaultDescription
messagesConversationMessage[]—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.
currentUserIdstring—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.
timeZonestring—IANA zone for days and times; the device's by default.
unreadFromIdstring | null—The divider goes before this message. conversationFirstUnread finds it.
onMarkRead() => void—Once, when the person reaches the bottom while the divider is shown.
stickToBottombooleantrueFollow 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 / emptynumber; string; string; string; string—Silence that starts a new run (5), the clock for Today, and the words.
classNamestring—Extra classes.