MessageTimeline

Conversation with older history

Yesterday

Ana Lopez7:30 PM

Morning! Is the launch checklist up to date?

7:33 PM

Mostly. Legal sign-off is still open.

Today

Ben Okafor6:30 AM

I’ll chase it after standup.

Chloé Martin7:30 AM

Thanks. The press kit is in the shared folder.

7:32 AM

Looks good. One typo on page two.

Ana Lopez9:30 AM

Fixed, and the screenshots are refreshed.

New messages

Ben Okafor11:00 AM

Great. Shall we freeze copy at 3pm?

11:02 AM

Works for me.

Ben Okafor is typing…

import { useCallback, useState } from 'react';
import { Button } from '@rookcom/monarch-react';
import { MessageRow, MessageTimeline, type MessageTimelineItem } from '@rookcom/monarch-react/collaboration';

const NOW = Date.parse('2026-03-02T12:00:00Z');

const PEOPLE: Record<string, string> = {
  ana: 'Ana Lopez',
  ben: 'Ben Okafor',
  chloe: 'Chloé Martin',
};

const LINES = [
  'Morning! Is the launch checklist up to date?',
  'Mostly. Legal sign-off is still open.',
  'I’ll chase it after standup.',
  'Thanks. The press kit is in the shared folder.',
  'Looks good. One typo on page two.',
  'Fixed, and the screenshots are refreshed.',
  'Great. Shall we freeze copy at 3pm?',
  'Works for me.',
];

type Demo = MessageTimelineItem & { text: string };

/** Minutes before `endAt` for each message: pairs close together group, the first ones fall on the previous day. */
const OFFSETS = [960, 957, 300, 240, 238, 120, 30, 28];

const OLDER_OFFSETS = [60, 58, 20, 18];

function history(count: number, endAt = NOW - 30 * 60_000): Demo[] {
  const authors = ['ana', 'ana', 'ben', 'chloe', 'chloe', 'ana', 'ben', 'ben'];
  const offsets = count === OFFSETS.length ? OFFSETS : OLDER_OFFSETS;
  return Array.from({ length: count }, (_, i) => ({
    id: `m${endAt}-${i}`,
    time: endAt - (offsets[i] ?? 0) * 60_000,
    authorId: authors[i % authors.length] ?? 'ana',
    text: LINES[i % LINES.length] ?? '',
  }));
}

const renderMessage = (m: Demo, ctx: { grouped: boolean }) => (
  <MessageRow
    author={{ name: PEOPLE[m.authorId ?? ''] ?? 'Someone', seed: m.authorId ?? 'unknown' }}
    time={m.time}
    now={NOW}
    grouped={ctx.grouped}
    timeDisplay="clock"
    timeZone="UTC"
  >
    {m.text}
  </MessageRow>
);

function LiveDemo() {
  const [items, setItems] = useState<Demo[]>(() => history(8));
  const [older, setOlder] = useState(2);
  const [loadingOlder, setLoadingOlder] = useState(false);
  const loadOlder = useCallback(() => {
    setLoadingOlder(true);
    setTimeout(() => {
      setItems((list) => {
        const first = Number(list[0]?.time ?? NOW);
        const page = history(4, first - 3 * 3_600_000).map((m, i) => ({
          ...m,
          id: `o${older}-${i}`,
        }));
        return [...page, ...list];
      });
      setOlder((n) => n - 1);
      setLoadingOlder(false);
    }, 700);
  }, [older]);
  const send = () =>
    setItems((list) => [
      ...list,
      { id: `n${list.length}`, time: NOW, authorId: 'ana', text: 'New message from the demo.' },
    ]);
  return (
    <div style={{ width: '100%', display: 'grid', gap: 8 }}>
      <div
        style={{
          height: 340,
          border: '1px solid var(--mn-color-border-subtle)',
          borderRadius: 'var(--mn-radius-lg)',
          overflow: 'hidden',
        }}
      >
        <MessageTimeline
          items={items}
          renderItem={renderMessage}
          firstUnreadId={items[items.length - 2]?.id ?? null}
          hasOlder={older > 0}
          loadingOlder={loadingOlder}
          onLoadOlder={loadOlder}
          header={<p style={{ margin: 0, fontSize: 13 }}>This is the start of #launch.</p>}
          status="Ben Okafor is typing…"
          now={NOW}
          timeZone="UTC"
        />
      </div>
      <div>
        <Button size="sm" onClick={send}>
          Add a message
        </Button>
      </div>
    </div>
  );
}

<LiveDemo />

Usage examples

In your own virtualiser

itemContent={(i, m) => {
  const prev = messages[i - 1];
  const newDay = !prev || formatMessageDay(prev.time) !== formatMessageDay(m.time);
  return (
    <>
      {newDay && <MessageTimelineDaySeparator>{formatMessageDay(m.time)}</MessageTimelineDaySeparator>}
      <MessageRow grouped={!newDay && shouldGroupMessages(prev, m)} … />
    </>
  );
}}

Purpose

Holds a conversation’s messages in a scrolling log that behaves like chat: it opens at the newest message, follows new ones while the reader is at the bottom, loads older history as they scroll up without the view jumping, and announces arrivals politely.

Use when

Channels, direct messages and threads.
Ticket and request conversations, interleaved with system rows.
Any reverse-chronological thread whose newest item sits next to a composer.

Avoid when

Feeds read top-down, newest first (activity, notifications): use ActivityTimeline.
Performance: MessageTimeline is not virtualised; every loaded message stays in the DOM. For histories of many thousands of loaded messages (Rook Chat), keep your virtualiser (react-virtuoso) and render MessageRow with the exported MessageTimelineDaySeparator, MessageTimelineUnreadDivider, shouldGroupMessages and formatMessageDay.

Design principles

The reader’s place is sacred: prepending older pages and late-loading images never move what they are reading.
Follow new messages only when the reader is at the bottom; otherwise count them on a “Jump to latest” button.
One live region for messages, a separate status for typing, so nothing is announced twice.
Data and fetching stay in the product; the timeline only asks for older pages through onLoadOlder.

API reference

import { MessageTimeline, MessageTimelineDaySeparator, MessageTimelineUnreadDivider, formatMessageDay, shouldGroupMessages } from '@rookcom/monarch-react/collaboration';

Export	Kind	Rendering	Root class
`MessageTimeline`	component	client	`.mn-message-timeline`
`MessageTimelineDaySeparator`	component	client	`.mn-message-timeline`
`MessageTimelineUnreadDivider`	component	client	`.mn-message-timeline`
`formatMessageDay`	utility	client	–
`shouldGroupMessages`	utility	client	–

Generic over your item type: items need id, time and an optional authorId; renderItem(item, { grouped, index, previous }) draws each one.

handleRef exposes scrollToBottom() and scrollToItem(id); the ref is forwarded to the root <div>.

shouldGroupMessages, formatMessageDay, MessageTimelineDaySeparator and MessageTimelineUnreadDivider are exported for products that keep their own virtualiser (react-virtuoso and similar).

Not virtualised: every loaded message is in the DOM. Paging keeps that bounded for typical conversations.

Generated from the TypeScript declarations of packages/react/src/patterns/collaboration/message-timeline.

Properties