super_navigation_sidebar #

A themeable, responsive app navigation sidebar for Flutter. One data model renders in three modes the host picks from the available width: a full expanded labelled tree with │ ├ └ connectors, an icon-only rail with hover flyouts, and an off-canvas drawer with a scrim. Typed NavNode<T> tree, badges, shortcut hints, header/footer slots, AppBar integration, localization, accessibility, RTL. Zero third-party dependencies.

Features #

🗂 Three layout modes — expanded (full labelled tree + connectors), rail (icon-only, hover flyouts), drawer (off-canvas, scrim) — one controller drives all three.
📐 Auto breakpoints — NavSidebarBreakpoints().modeFor(width) maps an available width to the right mode: expanded ≥ 1200 px · rail ≥ 768 px · drawer below.
🧭 AppBar integration — NavigationSidebarAppBar connects directly to the controller. Drawer mode inserts a hamburger; desktop mode adds a collapse toggle. Slots: title, pageTitle, globalSearch, middle, actions, custom builder. NavBreadcrumb<T> and NavigationSidebarSearchField are ready-made slot widgets.
🌳 Typed NavNode<T> tree — each node carries a strongly-typed value (route, screen enum, …); node.value reads with no casting.
🎭 Role derived from position — depth-0 leaf = direct; depth-0 branch = module; nested branch = group; nested leaf = item.
✅ Active-screen highlight + ancestor auto-expand — navigate(id) sets the active row, opens every ancestor module, and (in drawer mode) dismisses the drawer.
🔴 Badges — NavBadge(text, tone: NavBadgeTone.success/danger/muted).
⌨ Shortcut hints — two-key ['g', 'd']-style keycaps shown on hover. Visual hints only — wiring the keystroke is the host app's responsibility.
🔎 Built-in search & filter — searchable: true adds a filter field that matches every level, auto-expands hits, and highlights the matched run.
⭐ Quick Access favorites — favoritable: true adds per-row star toggles and a synthesized favorites band pinned at the top.
🔒 Permission-gated nodes — NavNode.locked + lockMessage dim a row, add a lock glyph, block navigation, and surface the reason as a tooltip.
🟢 Status dots — NavNode.status (open · closed · locked · attention) marks fiscal-period / ledger state before the label.
♿ Accessibility — every interactive row is wrapped in Semantics (button role, selected, expanded/collapsed state, lock/disable hints) and a Focus with onKeyEvent for keyboard activation (Enter / Space). The drawer close button has an accessible label.
🌐 Localization — NavigationSidebarLocalizations puts every user-facing string in one immutable class. English default; Arabic preset included.
🔐 Deep immutability — NavNode.children and NavSection.items are wrapped in List.unmodifiable() at construction.
🆔 Duplicate ID validation — debug-build assertion detects duplicate NavNode.id values with a clear error message.
🛡 Navigation safety — navigate() returns bool; onNavigate is only fired when navigation is actually applied (locked/disabled nodes are always refused).
🌍 RTL — connectors, flyouts, drawer slide direction, and all row padding mirror under Directionality(textDirection: TextDirection.rtl, …).
🔌 Zero dependencies — pure Flutter + Material.

Installation #

dependencies:
  super_navigation_sidebar: ^1.2.1

flutter pub get

Setup #

import 'package:super_navigation_sidebar/super_navigation_sidebar.dart';

MaterialApp(
  theme: ThemeData(
    extensions: const [NavigationSidebarThemeData.light],
  ),
  darkTheme: ThemeData(
    extensions: const [NavigationSidebarThemeData.dark],
  ),
  home: const MyApp(),
);

Quick start #

1 · Self-contained (no external controller) #

NavigationSidebar<String>(
  sections: [
    NavSection(title: 'Overview', items: [
      NavNode(id: 'dashboard', label: 'Dashboard',
              icon: Icons.dashboard_outlined, value: 'dashboard',
              shortcut: ['g', 'd']),
    ]),
    NavSection(title: 'Finance', items: [
      NavNode(id: 'accounts', label: 'Accounts',
              icon: Icons.menu_book_outlined, children: [
        NavNode(id: 'coa', label: 'Chart of Accounts', children: [
          NavNode(id: 'accounts_list', label: 'Account List',
                  icon: Icons.menu_book_outlined, value: 'accounts_list'),
        ]),
      ]),
    ]),
  ],
  active: 'dashboard',
  mode: NavSidebarMode.expanded,
  onNavigate: (node) => openScreen(node.value!),
);

Note (1.2+): NavNode and NavSection constructors are no longer const (children/items are wrapped in List.unmodifiable). Remove the const keyword from any const NavNode(…) or const NavSection(…) call sites.

2 · Responsive shell with AppBar #

class _AppShellState extends State<AppShell> {
  final _nav = NavigationSidebarController<String>(
    sections: mySections,
    active: 'dashboard',
  );
  String _screen = 'dashboard';

  @override
  Widget build(BuildContext context) {
    return LayoutBuilder(builder: (context, c) {
      final mode = const NavSidebarBreakpoints().modeFor(c.maxWidth);

      final sidebar = NavigationSidebar<String>(
        controller: _nav,
        mode: mode,
        header: (ctx, collapsed) => MyLogo(collapsed: collapsed),
        onNavigate: (node) => setState(() => _screen = node.value!),
      );

      if (mode == NavSidebarMode.drawer) {
        return Scaffold(
          appBar: NavigationSidebarAppBar(
            controller: _nav,
            mode: NavSidebarMode.drawer,
            pageTitle: NavBreadcrumb<String>(controller: _nav),
          ),
          body: Stack(children: [
            Positioned.fill(child: PageFor(screen: _screen)),
            Positioned.fill(child: sidebar),
          ]),
        );
      }

      return Row(children: [
        sidebar,
        Expanded(
          child: Column(children: [
            NavigationSidebarAppBar(
              controller: _nav,
              mode: mode,
              showCollapseToggle: true,
              pageTitle: NavBreadcrumb<String>(controller: _nav),
              globalSearch: NavigationSidebarSearchField(controller: _nav),
              actions: [NotificationBell(), UserAvatar()],
            ),
            Expanded(child: PageFor(screen: _screen)),
          ]),
        ),
      ]);
    });
  }

  @override
  void dispose() { _nav.dispose(); super.dispose(); }
}

AppBar integration #

`NavigationSidebarAppBar` #

A PreferredSizeWidget connected to the controller. Rebuilds automatically when the controller notifies (drawer open, collapsed flag, etc.).

Property	Type	Description
`controller`	`NavigationSidebarController`	Required.
`mode`	`NavSidebarMode`	Required. Determines leading controls.
`leading`	`Widget?`	Custom leading. Null → hamburger in drawer mode.
`title`	`Widget?`	App / product name.
`pageTitle`	`Widget?`	Breadcrumb or screen subtitle.
`globalSearch`	`Widget?`	A `NavigationSidebarSearchField` or custom widget.
`middle`	`Widget?`	Workspace switcher, env badge, etc.
`actions`	`List<Widget>?`	Trailing action buttons.
`showCollapseToggle`	`bool?`	Collapse ↔ expand toggle (default true in expanded/rail).
`builder`	`Function?`	Full custom content — overrides all slots.
`backgroundColor`	`Color?`	Falls back to `NavigationSidebarThemeData.surface`.
`showBorder`	`bool`	Bottom hairline border. Default `true`.
`height`	`double?`	Bar height. Default `kToolbarHeight` (56 px).
`localizations`	`NavigationSidebarLocalizations`	Semantic labels for built-in controls.

`NavBreadcrumb<T>` #

Reads controller.active and renders a ›-separated ancestor trail:

NavBreadcrumb<String>(
  controller: nav,
  separator: '  ›  ',       // default
  // style / activeStyle for custom TextStyles
)

`NavigationSidebarSearchField` #

A compact themed search field that drives controller.setQuery:

NavigationSidebarSearchField(
  controller: nav,
  hint: 'Search accounts, journals, reports…',
)

Localization #

All user-facing strings are in NavigationSidebarLocalizations. Pass a custom instance via NavigationSidebar.localizations and NavigationSidebarAppBar.localizations:

// English (default — no configuration needed):
NavigationSidebar<String>(controller: nav, mode: mode)

// Arabic (pair with RTL Directionality):
Directionality(
  textDirection: TextDirection.rtl,
  child: NavigationSidebar<String>(
    controller: nav,
    mode: mode,
    localizations: NavigationSidebarLocalizations.arabic,
  ),
)

// Partial override — only change what you need:
NavigationSidebar<String>(
  controller: nav, mode: mode,
  localizations: const NavigationSidebarLocalizations(
    searchHint: 'Buscar navegación…',
    lockedDefault: 'Acceso restringido',
  ),
)

Available strings #

Field	Default (English)
`searchHint`	`'Search navigation…'`
`searchEmpty`	`'No matches for "{query}"'`
`drawerTitle`	`'Navigation'`
`drawerCloseLabel`	`'Close navigation'`
`quickAccessTitle`	`'Quick Access'`
`addToQuickAccess`	`'Add to Quick Access'`
`removeFromQuickAccess`	`'Remove from Quick Access'`
`lockedDefault`	`"Locked — you don't have access"`
`shortcutPrefix`	`'Shortcut · '`
`shortcutSeparator`	`' then '`
`semanticExpanded`	`'expanded'`
`semanticCollapsed`	`'collapsed'`
`semanticLocked`	`'locked'`
`semanticDisabled`	`'disabled'`
`semanticToggleSidebar`	`'Toggle sidebar'`
`semanticOpenDrawer`	`'Open navigation'`

Data model #

`NavSection<T>` #

NavSection<String>(
  title: 'Finance',
  items: [...],           // List<NavNode<T>> — unmodifiable after construction
)

`NavNode<T>` #

Field	Type	Description
`id`	`NavNodeId` (String)	Required. Unique across the whole sidebar (validated in debug builds).
`label`	`String`	Required. Display text; search matches against this.
`icon`	`IconData?`	Leading icon.
`children`	`List<NavNode<T>>`	Child nodes. Unmodifiable after construction.
`value`	`T?`	Strongly-typed host payload.
`badge`	`NavBadge?`	Trailing badge pill.
`shortcut`	`List<String>?`	Visual hint only — `['g', 'd']` renders `G › D`.
`locked`	`bool`	Permission-gate: dim, lock glyph, block nav, tooltip.
`lockMessage`	`String?`	Tooltip on a locked row.
`status`	`NavNodeStatus`	State dot — `none`/`open`/`closed`/`locked`/`attention`.
`enabled`	`bool`	When `false`, row shown but not activatable.

Navigation safety #

navigate() returns bool: true = applied, false = refused (locked, disabled, or id not found). onNavigate is only fired on true:

// Safe — onNavigate is never called for locked / disabled nodes:
NavigationSidebar<String>(
  controller: nav,
  mode: mode,
  onNavigate: (node) => setState(() => _screen = node.value!),
)

// Programmatic nav with return-value check:
final ok = nav.navigate('wire');  // false if locked/disabled

Deep immutability #

NavNode.children and NavSection.items are List.unmodifiable after construction. Attempts to mutate throw UnsupportedError:

final node = NavNode(id: 'parent', label: 'Parent', children: [
  NavNode(id: 'child', label: 'Child'),
]);
node.children.add(NavNode(id: 'x', label: 'X')); // throws UnsupportedError

All structural changes must go through the controller (replaceSections, navigate, etc.) which notifies listeners correctly.

Duplicate ID validation #

In debug builds the controller asserts that every NavNode.id is unique:

NavigationSidebarController<String>(sections: myBadSections);
// → AssertionError: duplicate NavNode IDs detected: [myId]

Programmatic check (for tests or host validation):

final dups = NavOps.findDuplicateIds<String>(sections);
assert(dups.isEmpty, 'Duplicate nav ids: $dups');

Accessibility #

Every interactive row: Semantics (button role, selected, toggled expanded/collapsed, lock/disable hints) + Focus + onKeyEvent (Enter/Space).
Drawer close button: accessible label from localizations.drawerCloseLabel.
Locked/disabled rows: SystemMouseCursors.forbidden cursor.
Rail items: Tooltip with the node label; lock glyph shown on locked nodes.

ERP / banking features #

Built-in search & filter #

NavigationSidebar<String>(
  controller: nav,
  searchable: true,
  searchHint: 'Search accounts, journals, reports…',
);

Quick Access (favorites) #

NavigationSidebarController<String>(
  sections: sections,
  favorites: {'journalEntry', 'trialBalance'},
);
NavigationSidebar<String>(controller: nav, favoritable: true);

Permission-gated nodes #

NavNode(id: 'wire', label: 'Wire / SWIFT', icon: Icons.bolt_outlined,
        value: 'wire', locked: true,
        lockMessage: 'Requires Treasury Approver role');

Status dots #

NavNode(id: 'fy25q3', label: 'FY2025 · Q3', value: 'fy25q3',
        status: NavNodeStatus.open); // open · closed · locked · attention

Three modes #

`expanded` — 248 px full tree #

`rail` — 76 px icon column with hover flyouts #

`drawer` — 280 px off-canvas overlay #

// Place in a Stack + Positioned.fill; open via controller.openDrawer():
Stack(children: [
  Positioned.fill(child: MyPage()),
  Positioned.fill(
    child: NavigationSidebar<String>(
      controller: nav,
      mode: NavSidebarMode.drawer,
    ),
  ),
])

`NavigationSidebarController<T>` API #

Navigation #

Method	Returns	Description
`navigate(id)`	`bool`	Set active, open ancestors, close drawer. `false` if refused.

Expansion #

Method	Description
`expand(id)` · `collapse(id)` · `toggleNode(id)`	Open / close / flip a branch.
`expandAll()` · `collapseAll()`	All branches.

Rail / drawer #

Method / setter	Description
`toggleCollapsed()` · `collapsed = bool`	Flip expanded ↔ rail.
`openDrawer()` · `closeDrawer()` · `toggleDrawer()`	Drawer state.

Data #

Method	Description
`replaceSections(sections)`	Hot-swap the section forest. Validates duplicates in debug.
`setQuery(q)` · `matchSet()`	Search filter.
`toggleFavorite(id)` · `setFavorites(ids)`	Quick Access.

Reads #

Property / method	Description
`sections`	`List<NavSection<T>>`
`active` / `activeValue`	Active id / typed value.
`collapsed` / `drawerOpen` / `filtering`	State flags.
`isActive(id)` / `isExpanded(id)` / `ownsActive(id)`	Per-node queries.
`node(id)`	`NavNode<T>?` by id.
`matchSet()`	Matching ids + ancestors for the current query.
`favorites` / `favoriteNodes` / `isFavorite(id)`	Quick Access.

Theming #

ThemeData(
  extensions: [
    NavigationSidebarThemeData.light.copyWith(
      surface: const Color(0xFFFFFFFF),
      bg:      const Color(0xFFF5F3EF),
      border:  const Color(0xFFDDD7CE),
    ),
  ],
)

Architecture #

lib/
├── super_navigation_sidebar.dart   public barrel
└── src/
    ├── models.dart          NavSection · NavNode · NavBadge · NavBadgeTone
    │                        NavNodeRole · NavNodeId · NavNodeStatus
    │                        NavSidebarMode · NavSidebarBreakpoints · NavOps
    ├── theme.dart           NavigationSidebarThemeData (ThemeExtension)
    ├── localizations.dart   NavigationSidebarLocalizations
    ├── controller.dart      NavigationSidebarController (ChangeNotifier)
    │                        NavigationSidebarScope (InheritedNotifier)
    ├── sidebar.dart         NavigationSidebar<T> widget
    │                        _NavRow · _RailItem · _RailFlyout · _FlyoutRow
    │                        _NavBadgeChip · _ShortcutHint · _StarButton
    └── appbar.dart          NavigationSidebarAppBar · NavBreadcrumb<T>
                             NavigationSidebarSearchField

MVC: immutable NavNode<T> models → NavigationSidebarController<T> (ChangeNotifier) → thin NavigationSidebar<T> view → NavigationSidebarThemeData (ThemeExtension). The controller is published to descendant pages via NavigationSidebarScope<T> (InheritedNotifier).

Gotchas #

Host derives mode. Use LayoutBuilder + NavSidebarBreakpoints().modeFor(width).
Role is positional. Depth determines visual treatment, not an explicit field.
value vs id. value is the typed host payload; id is the nav identity.
Drawer must overlay. Place in Stack + Positioned.fill.
Register the theme extension. Without it the dark preset is used.
Shortcuts are visual hints only. Wire the actual keystroke yourself via Shortcuts/Actions.
No const NavNode/NavSection (1.2+). Constructors are non-const; remove the const keyword.
navigate() returns bool. Code calling it in a void context compiles unchanged; only explicit void variable assignment needs updating.

Additional information #

Changelog: CHANGELOG.md
Repository: https://github.com/GeniusSystems24/super_navigation_sidebar
Issues: https://github.com/GeniusSystems24/super_navigation_sidebar/issues
License: MIT — see LICENSE

super_navigation_sidebar 1.2.1 super_navigation_sidebar: ^1.2.1 copied to clipboard

Metadata