Skip to Content
BBRICKSv0.7.4
BlocksMessages

MessageHistoryList

The messages history, newest first as given: loading (skeleton rows), error (the reason and Try again), empty (a line that says whether a filter is on), else one MessageHistoryItem per message. The optional sent-by filter is a chip row (All / By TRNDR / By you); the pager slot sits under the list.

import { MessageHistoryList } from '@ergasti/bricks';

Examples

One message

The name, channel, status, when it was sent, who sent it, the audience and how many it reached; the body is shown in the page's language when the message has it.

Code
import { MessageHistoryItem, type BrandMessage } from '@ergasti/bricks';

const messages: BrandMessage[] = [
  { id: 1, name: 'Winter glow is live', body_en: 'Our Winter glow challenge starts today. Pick your gift in the app.', body_ar: 'تحدي Winter glow بدأ النهارده. اختار هديتك من التطبيق.', channel: 'whatsapp', status: 'sent', sent_at: '2026-11-12T10:00:00+02:00', sent_by: 'trndr_on_behalf', audience: { kind: 'all' }, recipients: 304, delivered: 298 },
  { id: 2, name: 'Top sellers bonus', body_en: 'You are in the top sellers group: the bonus is on.', body_ar: null, channel: 'sms', status: 'sent', sent_at: '2026-11-08T12:30:00+02:00', sent_by: 'brand', audience: { kind: 'group', groups: [{ id: 'g1', name: 'Top sellers' }] }, recipients: 4, delivered: 4 },
  { id: 3, name: 'Elite creators', body_en: 'A note for our Elite tier.', body_ar: null, channel: 'whatsapp', status: 'queued', sent_at: null, sent_by: 'trndr_on_behalf', audience: { kind: 'tier', tiers: ['elite'] }, recipients: null, delivered: null },
];

function Item() {
  return <div style={{ maxWidth: 620 }}><MessageHistoryItem message={messages[0]} /></div>;
}

History with a filter

A list of messages with a "sent by" filter, a pager slot, and loading, error and empty states.

Code
import { MessageHistoryList, type BrandMessage } from '@ergasti/bricks';
import { useState } from 'react';
import type { MessageSentByFilter } from '@ergasti/bricks';

const messages: BrandMessage[] = [
  { id: 1, name: 'Winter glow is live', body_en: 'Our Winter glow challenge starts today. Pick your gift in the app.', body_ar: 'تحدي Winter glow بدأ النهارده. اختار هديتك من التطبيق.', channel: 'whatsapp', status: 'sent', sent_at: '2026-11-12T10:00:00+02:00', sent_by: 'trndr_on_behalf', audience: { kind: 'all' }, recipients: 304, delivered: 298 },
  { id: 2, name: 'Top sellers bonus', body_en: 'You are in the top sellers group: the bonus is on.', body_ar: null, channel: 'sms', status: 'sent', sent_at: '2026-11-08T12:30:00+02:00', sent_by: 'brand', audience: { kind: 'group', groups: [{ id: 'g1', name: 'Top sellers' }] }, recipients: 4, delivered: 4 },
  { id: 3, name: 'Elite creators', body_en: 'A note for our Elite tier.', body_ar: null, channel: 'whatsapp', status: 'queued', sent_at: null, sent_by: 'trndr_on_behalf', audience: { kind: 'tier', tiers: ['elite'] }, recipients: null, delivered: null },
];

function History() {
  const [sentBy, setSentBy] = useState<MessageSentByFilter>('all');
  const shown = messages.filter((m) => sentBy === 'all' || m.sent_by === sentBy);
  return <div style={{ maxWidth: 620 }}><MessageHistoryList messages={shown} sentBy={{ value: sentBy, onChange: setSentBy }} /></div>;
}

Messages page

The history plus a way to ask TRNDR to send something (onContact or contactUrl) and a slot for the automatic messages.

Code
import { MessagesPanel, type BrandMessage } from '@ergasti/bricks';

const messages: BrandMessage[] = [
  { id: 1, name: 'Winter glow is live', body_en: 'Our Winter glow challenge starts today. Pick your gift in the app.', body_ar: 'تحدي Winter glow بدأ النهارده. اختار هديتك من التطبيق.', channel: 'whatsapp', status: 'sent', sent_at: '2026-11-12T10:00:00+02:00', sent_by: 'trndr_on_behalf', audience: { kind: 'all' }, recipients: 304, delivered: 298 },
  { id: 2, name: 'Top sellers bonus', body_en: 'You are in the top sellers group: the bonus is on.', body_ar: null, channel: 'sms', status: 'sent', sent_at: '2026-11-08T12:30:00+02:00', sent_by: 'brand', audience: { kind: 'group', groups: [{ id: 'g1', name: 'Top sellers' }] }, recipients: 4, delivered: 4 },
  { id: 3, name: 'Elite creators', body_en: 'A note for our Elite tier.', body_ar: null, channel: 'whatsapp', status: 'queued', sent_at: null, sent_by: 'trndr_on_behalf', audience: { kind: 'tier', tiers: ['elite'] }, recipients: null, delivered: null },
];

function Panel() {
  return <div style={{ maxWidth: 680 }}><MessagesPanel onContact={() => {}} history={{ messages }} automatic={<p className="kit-muted">Welcome and payout messages are sent automatically.</p>} /></div>;
}

Loading, error and empty

status="loading" and status="error" (with error for the reason and onRetry for Try again) replace the list; an empty messages says nothing was sent yet.

Code
import { Card, MessageHistoryList, type BrandMessage } from '@ergasti/bricks';

const messages: BrandMessage[] = [
  { id: 1, name: 'Winter glow is live', body_en: 'Our Winter glow challenge starts today. Pick your gift in the app.', body_ar: 'تحدي Winter glow بدأ النهارده. اختار هديتك من التطبيق.', channel: 'whatsapp', status: 'sent', sent_at: '2026-11-12T10:00:00+02:00', sent_by: 'trndr_on_behalf', audience: { kind: 'all' }, recipients: 304, delivered: 298 },
  { id: 2, name: 'Top sellers bonus', body_en: 'You are in the top sellers group: the bonus is on.', body_ar: null, channel: 'sms', status: 'sent', sent_at: '2026-11-08T12:30:00+02:00', sent_by: 'brand', audience: { kind: 'group', groups: [{ id: 'g1', name: 'Top sellers' }] }, recipients: 4, delivered: 4 },
  { id: 3, name: 'Elite creators', body_en: 'A note for our Elite tier.', body_ar: null, channel: 'whatsapp', status: 'queued', sent_at: null, sent_by: 'trndr_on_behalf', audience: { kind: 'tier', tiers: ['elite'] }, recipients: null, delivered: null },
];

function States() {
  return (
    <div style={{ maxWidth: 620, display: 'grid', gap: 16 }}>
      <Card><MessageHistoryList messages={[]} status="loading" /></Card>
      <Card><MessageHistoryList messages={[]} status="error" error="Messages could not be loaded. Check your connection." onRetry={() => {}} /></Card>
      <Card><MessageHistoryList messages={[]} /></Card>
    </div>
  );
}

With a pager

pager sits under the list: pass the kit Pager and fetch the page on change. labels and itemLabels override single words (here the list's name and the not-sent line).

Code
import { MessageHistoryList, Pager, type BrandMessage } from '@ergasti/bricks';
import { useState } from 'react';

const messages: BrandMessage[] = [
  { id: 1, name: 'Winter glow is live', body_en: 'Our Winter glow challenge starts today. Pick your gift in the app.', body_ar: 'تحدي Winter glow بدأ النهارده. اختار هديتك من التطبيق.', channel: 'whatsapp', status: 'sent', sent_at: '2026-11-12T10:00:00+02:00', sent_by: 'trndr_on_behalf', audience: { kind: 'all' }, recipients: 304, delivered: 298 },
  { id: 2, name: 'Top sellers bonus', body_en: 'You are in the top sellers group: the bonus is on.', body_ar: null, channel: 'sms', status: 'sent', sent_at: '2026-11-08T12:30:00+02:00', sent_by: 'brand', audience: { kind: 'group', groups: [{ id: 'g1', name: 'Top sellers' }] }, recipients: 4, delivered: 4 },
  { id: 3, name: 'Elite creators', body_en: 'A note for our Elite tier.', body_ar: null, channel: 'whatsapp', status: 'queued', sent_at: null, sent_by: 'trndr_on_behalf', audience: { kind: 'tier', tiers: ['elite'] }, recipients: null, delivered: null },
];

function Paged() {
  const [page, setPage] = useState(1);
  return (
    <div style={{ maxWidth: 620 }}>
      <MessageHistoryList
        messages={messages.slice(page - 1, page + 1)}
        pager={<Pager page={page} lastPage={2} total={3} perPage={2} loading={false} label="Messages" onPage={setPage} />}
        labels={{ label: 'Messages to Glow Lab creators' }} itemLabels={{ notSent: 'Waiting to go out' }}
      />
    </div>
  );
}

contactUrl (the API's contact_url) makes "Contact TRNDR" a link; empty or null hides it. The history takes the same states as the list.

Code
import { MessagesPanel, type BrandMessage } from '@ergasti/bricks';

const messages: BrandMessage[] = [
  { id: 1, name: 'Winter glow is live', body_en: 'Our Winter glow challenge starts today. Pick your gift in the app.', body_ar: 'تحدي Winter glow بدأ النهارده. اختار هديتك من التطبيق.', channel: 'whatsapp', status: 'sent', sent_at: '2026-11-12T10:00:00+02:00', sent_by: 'trndr_on_behalf', audience: { kind: 'all' }, recipients: 304, delivered: 298 },
  { id: 2, name: 'Top sellers bonus', body_en: 'You are in the top sellers group: the bonus is on.', body_ar: null, channel: 'sms', status: 'sent', sent_at: '2026-11-08T12:30:00+02:00', sent_by: 'brand', audience: { kind: 'group', groups: [{ id: 'g1', name: 'Top sellers' }] }, recipients: 4, delivered: 4 },
  { id: 3, name: 'Elite creators', body_en: 'A note for our Elite tier.', body_ar: null, channel: 'whatsapp', status: 'queued', sent_at: null, sent_by: 'trndr_on_behalf', audience: { kind: 'tier', tiers: ['elite'] }, recipients: null, delivered: null },
];

function PanelLink() {
  return <div style={{ maxWidth: 680 }}><MessagesPanel contactUrl="https://wa.me/201000000000" history={{ messages: [], status: 'loading' }} /></div>;
}

Props

Prop

Type

Labels

Every word this component draws, in both languages. Override one per component and language with BricksProvider labels under the key messageHistoryList, or with the component's own prop where it has one. A {name} is a value the component fills in.

messageHistoryList
KeyEnglishArabic
labelMessages sent to your creatorsالرسايل اللي اتبعتت لصنّاع المحتوى بتوعك
filterSent byمين بعتها
allAllالكل
byTrndrBy TRNDRفريق TRNDR
byBrandBy youإنت
emptyNo messages sent to your creators yet.لسه مفيش رسايل اتبعتت لصنّاع المحتوى بتوعك.
emptyFilteredNo messages sent this way yet.لسه مفيش رسايل اتبعتت بالطريقة دي.

Design guidance

How the BRICKS design system uses MessageHistoryList. Written in docs/content/components/MessageHistoryList.md; the props above are read from the code, which wins where the two disagree.

The brand's message history: an optional "Sent by" chip filter, one MessageHistoryItem per message (newest first as given), loading / error / empty states and a pager slot; use it inside MessagesPanel or a card.

It is read-only and filters nothing itself: the sent-by chips (All / By TRNDR / By you) only report the choice, and the server filters. The empty line says whether a filter is on.

Anatomy

  1. Tools (with sentBy): FilterChips "Sent by".
  2. List: ul named "Messages sent to your creators", one item per message.
  3. States: skeleton rows; error + "Try again"; empty line.
  4. Pager (ready and non-empty): your pager node.

Variants

SetupWhen
No sentByPlain history.
sentByFilter by sender.
pagerPaged history (kit Pager).

States

StateTrigger
Readydefault.
Loadingstatus="loading".
Errorstatus="error", error, onRetry.
Empty"No messages sent to your creators yet."
Empty, filteredfilter not "all": "No messages sent this way yet."

Usage

const [sentBy, setSentBy] = useState<MessageSentByFilter>('all');
const list = usePaged<BrandMessage>(urls.messages, { params: { sent_by: sentBy }, perPage: 10 });

<MessageHistoryList messages={list.rows} status={list.status === 'idle' ? 'ready' : list.status} error={list.error?.message} onRetry={list.reload}
  sentBy={{ value: sentBy, onChange: setSentBy }}
  pager={<Pager page={list.page} lastPage={list.lastPage} total={list.total} perPage={10} loading={list.status === 'loading'} label="Messages" onPage={list.setPage} />} />

Where it appears

  • Library only: the v3 brand mock has no Messages screen (built for the live console). Inside MessagesPanel's history card; missing-brand gallery.

Guidelines

Do

  • Reset to page 1 when the filter changes.

Don't

  • Don't filter on the client; the list only reports the chip.

RTL and Arabic

  • Mirrors. Arabic: "مين بعتها", "الكل", "فريق TRNDR", "إنت".

Tokens

--ink-3 (empty line), --rasp-50 and --bad (error box); chips' and items' tokens.

Accessibility

  • A named list of named articles; loading aria-busy, errors role="alert" (mounted with their text).
  • The sent-by chips are a FilterChips radiogroup with one tab stop. Keep sentBy.value one of 'all' | 'trndr_on_behalf' | 'brand': with any other value no chip shows as selected.

Found in the source

  • ARIA attributes set: aria-label.

Read from the component's source and tests. See Accessibility for the patterns the library follows.

See also: useLanguage · Card

Source

src/blocks/messages/MessageHistoryList.tsx (line 70) on GitHub.

On this page