NavGroups
The nav list shared by the sidebar, the icon rail and the phone sheet: the mock's .nav buttons (icon, label, count or NEW pill), group headings (PR portal .grp), indented children and disabled "later" items, and collapsible groups (the console's More, open while one of its screens is current; closed, it carries their waiting total).
import { NavGroups } from '@ergasti/bricks';Examples
The navigation list
Items are links (give href) or buttons (onSelect); a count, a "hot" count, a NEW or LATER badge, and disabled are built in. Labels may be a string or { en, ar }. The dark background is the sidebar's: this example draws it itself.
Code
import { useState } from 'react';
import { NavGroups } from '@ergasti/bricks';
import { brandNav } from './nav';
function List() {
const [active, setActive] = useState('motivation');
return (
<div style={{ background: 'var(--shell-side-bg)', borderRadius: 18, padding: 12, maxWidth: 280 }}>
<NavGroups groups={brandNav} activeId={active} onSelect={(item) => setActive(item.id)} />
</div>
);
}Props
Prop
Type
Design guidance
How the BRICKS design system uses NavGroups. Written in docs/content/components/NavGroups.md; the props above are read from the code, which wins where the two disagree.
The navigation list shared by the sidebar, the icon rail and the phone sheet: items with icon, label and count or badge, group headings, indented children, disabled "LATER" items and collapsible groups; feed it NavGroup data and the current id.
It renders the mocks' .nav buttons. Brand dashboard: one flat group (the v3 mock), plus, in the library's console nav, a collapsible "More" (Videos, Messages, Fraud checks, Brand library), open while one of its screens is current and, when closed, carrying its waiting total. PR Portal: headings ("Campaigns") with indented children (Affiliate programs, Challenges) and a "Next sprint" group of disabled LATER items. Sidebar and MobileNavSheet render it; use it directly only for a custom nav.
Anatomy
- Item (
.kit-shell-nav-item): a<button>, or an<a>withhref; 14px, padding 11px 14px, radius 14, gap 12.- Icon (19px, a kit icon name or any element).
- Label (clamped to two lines).
- End: a count pill (
.kit-shell-ct, "304", "999+" above 999; red whenhot), or a lime "NEW" badge (.kit-shell-nw), or a grey "LATER" (.kit-shell-soon).
- Heading (
.kit-shell-grp): 11px uppercase grey, in arole="group". - Indented child (
indent): 46px start padding, no icon. - Collapsible group: a disclosure item ("More", ellipsis icon, chevron rotating 180°), then its sublist (22px start padding).
- Rail mode (
rail): icons only; initials badge (.kit-shell-abbr) for items without an icon; counts become dots (.kit-shell-dot, lime when hot); headings become a 32px rule.
Variants
NavItem / NavGroup field | Look | Use when |
|---|---|---|
count | Count pill | Waiting work (Creators 304, Approvals 7). |
count + hot | Red pill | Only late work (overdue videos, open fraud). |
badge: { tone: 'new' } | Lime "NEW" | A new screen (Find creators). Replaces the count. |
badge: { tone: 'soon' } + disabled | Grey "LATER", muted, not clickable | Planned screens (PR "Next sprint"). |
indent | Indented child, no icon | Sub-destinations under a heading. |
NavGroup.heading | Small uppercase title | Sections (PR "Campaigns"). |
NavGroup.collapsible | Disclosure with chevron | Secondary screens ("More"). |
rail | 72px icon rail | Tablet tier. |
States
| State | How | Look |
|---|---|---|
| Active | activeId matches | Raspberry fill, white, aria-current="page". |
| Hover | pointer | --shell-nav-hover background. |
| Focus-visible | keyboard | Inverse focus ring. |
| Disabled | disabled | Muted ink, no hover, not focusable. |
| Group closed | collapsible, not active inside | Sublist hidden; the waiting total shows on the disclosure. |
| Group forced open | an item inside is active | Always open. |
Types
NavItem: id, label: string | { en, ar }, icon?, count?, hot?, badge?: { label, tone: 'new' | 'soon' }, href?, onSelect?, disabled?, indent?.
Helpers: flattenNav(groups), labelText(label, language).
NavGroup (groups): { id, heading?, items, collapsible?, icon?, defaultOpen? }.
Usage
const PR_NAV: NavGroup[] = [
{ id: 'top', items: [
{ id: 'home', label: { en: 'Home', ar: 'الرئيسية' }, icon: 'home' },
{ id: 'approvals', label: { en: 'Approvals', ar: 'الموافقات' }, icon: 'check', count: 7 },
{ id: 'brands', label: { en: 'Brands', ar: 'البراندات' }, icon: 'flag' },
] },
{ id: 'campaigns', heading: { en: 'Campaigns', ar: 'الحملات' }, items: [
{ id: 'programs', label: { en: 'Affiliate programs', ar: 'برامج الأفلييت' }, indent: true },
{ id: 'challenges', label: { en: 'Challenges', ar: 'التحديات' }, indent: true, count: 3 },
] },
{ id: 'next', heading: { en: 'Next sprint', ar: 'السبرنت الجاي' }, items: [
{ id: 'payouts', label: { en: 'Payouts', ar: 'المدفوعات' }, icon: 'payments', disabled: true, badge: { label: { en: 'LATER', ar: 'بعدين' }, tone: 'soon' } },
] },
];
<div className="kit-shell-nav"><NavGroups groups={PR_NAV} activeId="challenges" onSelect={go} /></div>import { Shield, Video } from 'lucide-react';
import type { NavGroup } from '@ergasti/bricks';
// Brand dashboard "More": collapsible; closed, it shows the waiting total
const more: NavGroup = { id: 'more', collapsible: true, items: [
{ id: 'videos', label: { en: 'Videos', ar: 'الفيديوهات' }, icon: <Video />, count: 4, hot: true },
{ id: 'fraud', label: { en: 'Fraud checks', ar: 'فحص الاحتيال' }, icon: <Shield />, count: 1, hot: true },
] };Where it appears
- Brand › sidebar and phone sheet (all screens). Screens:
Brand*. - PR Portal › sidebar (all screens). Screens:
Pr*.
Guidelines
Do
- Use
{ en, ar }labels. - Show counts only for work waiting on the user;
hotonly for late work. - Give top-level items icons; leave indented children without.
Don't
- Don't show a badge and a count together (the badge wins).
- Don't nest deeper than one indent level.
- Don't hide unavailable destinations users expect; disable them with a "LATER" badge.
RTL and Arabic
- Icons on the right; counts on the left; indentation from the right.
- Arabic headings are not uppercased; rail initials use one Arabic letter.
Tokens
--shell-nav-ink, --shell-nav-hover, --shell-nav-active (--color-nav-active, --rasp), --shell-nav-muted, --shell-nav-pad-block, --shell-grp-ink, --color-count-hot (--bad), --color-nav-count-ink, --color-nav-count-active-bg, --lime, --olive, --rasp-soft, --focus-ring-inverse.
Accessibility
- Items are
<a>(with a safehref) or<button type="button">; the current one hasaria-current="page". - Headings label their
role="group"; on the rail the heading text stays for screen readers. - Collapsible groups:
aria-expandedandaria-controls. - Rail:
titletooltips andaria-labelwith the count ("Creators (304)"); dots and initials arearia-hidden. - Counts are
dir="ltr". Items are about 42px tall on desktop (40px in the PR theme) and at least 44px on touch tiers (≤1024px).
Found in the source
- Roles in the markup:
group. - ARIA attributes set:
aria-current,aria-expanded,aria-controls,aria-label,aria-hidden,aria-labelledby. - Its tests cover: “draws the PR portal’s group headings as labelled groups, indented children, and a disabled LATER item”; “on the rail: names come from aria-label and title, counts become dots, headings stay for screen readers only”; “on the rail: an indented item (no icon) shows its initials in a badge, not a cut-off label”; “labels everything in Arabic”; “is keyboard-operable: Tab reaches each item, Enter picks it, Enter on More opens it”; “is the labelled nav landmark with the brand, the nav, the card and the footer”.
Read from the component's source and tests. See Accessibility for the patterns the library follows.
Related
Sidebar,MobileNavSheet: where it renders.BottomNav: the phone tab bar (no counts).PillTabs/Segmented: in-page navigation.
See also: useLanguage · AppShell · BrandMark
Source
src/shell/NavGroups.tsx (line 48) on GitHub.