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.
| Key | English | Arabic |
|---|---|---|
title | Notifications | الإشعارات |
bell | Notifications | الإشعارات |
fresh | {n} new | {n} جديد |
markAll | Mark all as read | علّم الكل كمقروء |
unread | unread | مش مقروء |
none | No notifications yet. | لسه مفيش إشعارات. |
seeAll | See everything in the Activity log → | شوف كل حاجة في سجل النشاط ← |
loading | Loading notifications… | بنحمّل الإشعارات… |
failed | Couldn't load notifications. | معرفناش نحمّل الإشعارات. |
retry | Try 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
- Bell (
button.kit-bell):Icon bell,aria-expanded, named "Notifications, 3 new". - Badge (
span.kit-nbadge,aria-hidden, LTR): the count, "99+" above 99. - Panel (
div.kit-notif,role="dialog", "Notifications"): absolute under the bell at the inline end, 390px (max viewport − 32), radius 22,--lineborder. - Head (
.kit-nh): title + "N new" bad-tone pill; "Mark all as read" link-button. - Rows (
ul.kit-nl>button.kit-ni): tone tile with the icon, the sentence and the "when" line, an unread dot (with hidden "unread"). - 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
| State | Trigger | Look |
|---|---|---|
| Closed, unread | unread > 0 | Bell + badge |
| Closed, all read | 0 unread | Bell only; no "N new", no "Mark all as read" |
| Open | click bell | Panel; onOpen runs once per opening |
| Unread row | unread: true | Tinted row + dot |
| Loading, empty | status="loading", no items | "Loading notifications…" (role="status") |
| Loading, with rows | status="loading" | Rows stay, list aria-busy |
| Error | status="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 |
| Empty | items=[] | "No notifications yet." |
More than max | many items | First 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
unreadCountwhen the list is a page of the server's notices. - Reload in
onOpenso 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-controlswhile open; the badge isaria-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 getsaria-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.
Related
AppHeader,TopbarMenu,UserMenu: the header around it.ActivityLog: where "See everything" goes.ToastRegion: transient messages.
See also: useFocusTrap · Icon · useLanguage · DetailsBars · DetailsDrawer · DialogSkeleton · Drawer
Source
src/kit/patterns/NotificationsMenu.tsx (line 55) on GitHub.