Skip to Content
BBRICKSv0.7.4
KitOverlays

NotificationsMenu

The v3 topbar bell (#notif): a round button with the unread count, and a dropdown panel: "Notifications · N new", "Mark all as read", the latest max (6) items (unread ones tinted with a dot), and "See everything in the Activity log →". Opening an item calls onOpenItem (the app marks it read and goes to its target) and closes the panel. Escape and an outside click close it; focus is held in the panel while open and returns to the bell. Data comes from the app (E13); this is the shell only. With unreadCount the badge shows the server's count; status covers loading and a failed load (onRetry); onOpen lets the app reload on each opening.

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

Examples

Bell menu

A bell with an unread count that opens a list of notices; unread ones are marked, and "Mark all as read" and "See all" are yours to handle.

Code
import { NotificationsMenu, useLanguage, type NotificationItem } from '@ergasti/bricks';

function Bell() {
  const language = useLanguage();
  const items: NotificationItem[] = language === 'ar'
    ? [
        { id: 1, text: <>TRNDR وافقت على طلب انضمام <b>كريم حسني</b>. الكوبون KARI0329 شغال.</>, when: 'من ساعتين', icon: 'user', tone: 'lime', unread: true },
        { id: 2, text: <>المحفظة <b>قربت تخلص (فاضل 17%)</b>. اشحن عشان الكوبونات تفضل شغالة.</>, when: 'النهارده', icon: 'wallet', tone: 'rasp', unread: true },
        { id: 3, text: <>طلب التحدي <b>Ramadan preview</b> اترفض. شوف السبب.</>, when: 'من 5 ساعات', icon: 'flag', tone: 'butter', unread: false },
      ]
    : [
        { id: 1, text: <>TRNDR approved <b>Karim Hosny</b>’s join request. Coupon KARI0329 is live.</>, when: '2 hours ago', icon: 'user', tone: 'lime', unread: true },
        { id: 2, text: <>Your wallet is <b>low (17% left)</b>. Top up so coupons keep working.</>, when: 'Today', icon: 'wallet', tone: 'rasp', unread: true },
        { id: 3, text: <>Your challenge request <b>Ramadan preview</b> was rejected. See the reason.</>, when: '5 hours ago', icon: 'flag', tone: 'butter', unread: false },
      ];
  return (
    <div style={{ display: 'flex', justifyContent: 'flex-end' }}>
      <NotificationsMenu items={items} onOpenItem={() => {}} onMarkAllRead={() => {}} onSeeAll={() => {}} />
    </div>
  );
}

Fewer rows, and nothing new

max caps how many notices the menu lists before "See all" (default 6); with no items the menu says there is nothing new.

Code
import { NotificationsMenu, type NotificationItem } from '@ergasti/bricks';

function MaxAndEmpty() {
  const items: NotificationItem[] = [1, 2, 3, 4].map((id) => ({ id, text: `Creator ${id} joined Glow Lab.`, when: `${id} h ago`, icon: 'user', tone: 'lime', unread: id < 3 }));
  return (
    <div style={{ display: 'flex', justifyContent: 'space-between' }}>
      <NotificationsMenu items={[]} onOpenItem={() => {}} onSeeAll={() => {}} />
      <NotificationsMenu items={items} max={2} onOpenItem={() => {}} onSeeAll={() => {}} />
    </div>
  );
}

Server count and load states

unreadCount is the server's count when the list holds only the latest rows (the badge caps at 99+). status="loading" and status="error" (with onRetry) cover the fetch; onOpen runs each time the panel opens, so you can reload there. A row without icon / tone shows the bell on sky.

Code
import { NotificationsMenu, type NotificationItem } from '@ergasti/bricks';

function ServerCountAndStates() {
  const items: NotificationItem[] = [
    { id: 1, text: 'Payout sent to 38 creators.', when: '2 days ago', unread: true },
    { id: 2, text: 'Coupon KARI0329 is live.', when: 'Yesterday', unread: false },
  ];
  return (
    <div style={{ display: 'flex', justifyContent: 'flex-end', gap: 12 }}>
      <NotificationsMenu items={items} unreadCount={14} onOpen={() => {}} onOpenItem={() => {}} onSeeAll={() => {}} />
      <NotificationsMenu items={[]} status="loading" onOpenItem={() => {}} onSeeAll={() => {}} />
      <NotificationsMenu items={[]} status="error" onRetry={() => {}} unreadCount={3} onOpenItem={() => {}} onSeeAll={() => {}} />
    </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 notifications, or with the component's own prop where it has one. A {name} is a value the component fills in.

notifications
KeyEnglishArabic
titleNotificationsالإشعارات
bellNotificationsالإشعارات
fresh{n} new{n} جديد
markAllMark all as readعلّم الكل كمقروء
unreadunreadمش مقروء
noneNo notifications yet.لسه مفيش إشعارات.
seeAllSee everything in the Activity log →شوف كل حاجة في سجل النشاط ←
loadingLoading notifications…بنحمّل الإشعارات…
failedCouldn't load notifications.معرفناش نحمّل الإشعارات.
retryTry againجرّب تاني

Design guidance

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

The topbar bell with an unread count that opens a dropdown of the latest notifications; use it once per dashboard in the header tools.

NotificationsMenu is the v3 topbar #notif: a round bell button with a raspberry badge (99+ above 99) and, when opened, a 390px panel: "Notifications · N new", "Mark all as read", the latest max (6) rows (unread ones tinted with a dot) and "See everything in the Activity log →". Opening a row calls onOpenItem (the app marks it read and navigates) and closes the panel. Escape and an outside click close it; focus is held in the panel while open and returns to the bell. Data comes from the app; this is the shell only.

Anatomy

  1. Bell (button.kit-bell): Icon bell, aria-expanded, named "Notifications, 3 new".
  2. Badge (span.kit-nbadge, aria-hidden, LTR): the count, "99+" above 99.
  3. Panel (div.kit-notif, role="dialog", "Notifications"): absolute under the bell at the inline end, 390px (max viewport − 32), radius 22, --line border.
  4. Head (.kit-nh): title + "N new" bad-tone pill; "Mark all as read" link-button.
  5. Rows (ul.kit-nl > button.kit-ni): tone tile with the icon, the sentence and the "when" line, an unread dot (with hidden "unread").
  6. Footer (button.kit-nf): "See everything in the Activity log →".

Variants

Row tone (KpiTone): 'lime', 'rasp', 'butter', 'sky' (default), 'lilac'. Row icon: any IconName (default 'bell'). Badge source: unread rows in items, or unreadCount from the server.

States

StateTriggerLook
Closed, unreadunread > 0Bell + badge
Closed, all read0 unreadBell only; no "N new", no "Mark all as read"
Openclick bellPanel; onOpen runs once per opening
Unread rowunread: trueTinted row + dot
Loading, emptystatus="loading", no items"Loading notifications…" (role="status")
Loading, with rowsstatus="loading"Rows stay, list aria-busy
Errorstatus="error""Couldn't load notifications." alert + "Try again" (with onRetry). The badge, "N new" and "Mark all as read" stay: they come from unreadCount (the server's count), which is still known when the list fails; pass unreadCount={undefined} and omit onMarkAllRead if your count failed too
Emptyitems=[]"No notifications yet."
More than maxmany itemsFirst max rows

Types

NotificationItem: id, text (may hold <b>), when, icon?, tone?, unread.

Usage

const items: NotificationItem[] = [
  { id: 1, text: <>TRNDR approved <b>Karim Hosny</b>’s join request. Coupon KARI0329 is live.</>, when: '2 hours ago', icon: 'user', tone: 'lime', unread: true },
  { id: 2, text: <>Your wallet is <b>low (17% left)</b>. Top up so coupons keep working.</>, when: 'Today', icon: 'wallet', tone: 'rasp', unread: true },
  { id: 3, text: <>Your challenge request <b>Ramadan preview</b> was rejected. See the reason.</>, when: '5 hours ago', icon: 'flag', tone: 'butter', unread: false },
];

<NotificationsMenu items={items} onOpenItem={openNotification} onMarkAllRead={markAllRead} onSeeAll={() => navigate('#log')} />

Server count and fetch states:

<NotificationsMenu items={latest} unreadCount={data?.unread_count} status={loading ? 'loading' : error ? 'error' : 'ready'}
  onRetry={reload} onOpen={reload} onOpenItem={openNotification} onSeeAll={() => navigate('#log')} />

In the app header:

<AppHeader title="Home" subtitle="Good morning, HushUp" onToggleLanguage={toggleLanguage}
  search={<HeaderSearch placeholder="Search creators or coupons" fetcher={search} groupLabels={{ creators: 'Creators', coupons: 'Coupons' }} onSelect={go} />}
  actions={<>
    <TopbarMenu label="Help" trigger={<Icon name="help" />} items={[{ id: 'help', label: 'Help centre' }]} />
    <NotificationsMenu items={items} onOpenItem={open} onMarkAllRead={markAllRead} onSeeAll={seeAll} />
  </>} />

Where it appears

  • Brand dashboard › topbar › bell (every page).
  • PR Portal › topbar › bell with count and panel.
  • Screens: every Brand and PR screen header (e.g. Home, PR · Home).

Guidelines

Do

  • Write each notice as a full sentence with the name in <b>.
  • Pass unreadCount when the list is a page of the server's notices.
  • Reload in onOpen so the panel is fresh.

Don't

  • Don't put more than one bell on a page.
  • Don't use notifications for errors the user is causing now; use a Toast or Banner.

RTL and Arabic

  • The panel anchors at the inline end (left edge in Arabic); rows mirror. Arabic line height via --lh-ar.

Tokens

--card, --line, --ink, --ink-3, --soft, --bg, --rasp, --rasp-50, --rasp-ink, --bad, --focus-ring, --focus-ring-inset, --font-family-display, --lh-ar.

Accessibility

  • Bell: a native button named with the count ("Notifications, 3 new" / "Notifications"), aria-expanded, aria-controls while open; the badge is aria-hidden (the name carries the number).
  • Panel: role="dialog" named "Notifications". On open, focus moves to the first focusable control in the panel ("Mark all as read" when there are unread items, otherwise the first row), is trapped inside, and returns to the bell on close. Escape and a click outside close it.
  • Rows are buttons; an unread row has hidden "unread" text, so the dot is not the only cue.
  • Error: a role="alert" block; pressing "Try again" first moves focus to the panel, so focus is not lost when the button is replaced by the loading line.
  • Loading with no rows: a role="status" line; with rows, the list gets aria-busy.

Found in the source

  • Roles in the markup: dialog, alert, status.
  • ARIA attributes set: aria-label, aria-expanded, aria-controls, aria-hidden, aria-busy.
  • It traps focus while open and returns it on close.
  • It moves focus in code.
  • Its tests cover: “the bell says how many are new and opens a labelled panel: ”; “keyboard: focus moves in, Tab stays inside, Escape closes and returns focus to the bell”; “Arabic + RTL: loading, error and retry words; provider labels override ”; “F5: the loading line is a status that is not itself busy (so it is announced)”; “F6: Enter on ”.

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

See also: useFocusTrap · Icon · useLanguage · DetailsBars · DetailsDrawer · DialogSkeleton · Drawer

Source

src/kit/patterns/NotificationsMenu.tsx (line 55) on GitHub.

On this page