Skip to Content
BBRICKSv0.7.4
ShellFrame

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

  1. Item (.kit-shell-nav-item): a <button>, or an <a> with href; 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 when hot), or a lime "NEW" badge (.kit-shell-nw), or a grey "LATER" (.kit-shell-soon).
  2. Heading (.kit-shell-grp): 11px uppercase grey, in a role="group".
  3. Indented child (indent): 46px start padding, no icon.
  4. Collapsible group: a disclosure item ("More", ellipsis icon, chevron rotating 180°), then its sublist (22px start padding).
  5. 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 fieldLookUse when
countCount pillWaiting work (Creators 304, Approvals 7).
count + hotRed pillOnly late work (overdue videos, open fraud).
badge: { tone: 'new' }Lime "NEW"A new screen (Find creators). Replaces the count.
badge: { tone: 'soon' } + disabledGrey "LATER", muted, not clickablePlanned screens (PR "Next sprint").
indentIndented child, no iconSub-destinations under a heading.
NavGroup.headingSmall uppercase titleSections (PR "Campaigns").
NavGroup.collapsibleDisclosure with chevronSecondary screens ("More").
rail72px icon railTablet tier.

States

StateHowLook
ActiveactiveId matchesRaspberry fill, white, aria-current="page".
Hoverpointer--shell-nav-hover background.
Focus-visiblekeyboardInverse focus ring.
DisableddisabledMuted ink, no hover, not focusable.
Group closedcollapsible, not active insideSublist hidden; the waiting total shows on the disclosure.
Group forced openan item inside is activeAlways 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; hot only 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 safe href) or <button type="button">; the current one has aria-current="page".
  • Headings label their role="group"; on the rail the heading text stays for screen readers.
  • Collapsible groups: aria-expanded and aria-controls.
  • Rail: title tooltips and aria-label with the count ("Creators (304)"); dots and initials are aria-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.

See also: useLanguage · AppShell · BrandMark

Source

src/shell/NavGroups.tsx (line 48) on GitHub.

On this page