Skip to main content
Quick Setup with Neo CLI: The easiest way to get started with the sidebar layout is using the Neo CLI with the sidebar template. This automatically sets up the complete sidebar layout with proper routing, state management, and file structure.For existing projects, consider creating a new Neo project to see the recommended setup and copy what you need.

​
Example

NeoSidebarLayout(
  sidebarChildren: [
    NeoSidebarButton(
      label: "Dashboard",
      icon: PhosphorIcons.house,
      isActive: true,
      onPressed: () => context.router.push(const DashboardRoute()),
    ),
    NeoSidebarButton(
      label: "Products",
      icon: PhosphorIcons.tag,
      onPressed: () => context.router.push(const ProductsRoute()),
    ),
    NeoSidebarButton(
      label: "Orders",
      icon: PhosphorIcons.receipt,
      badgeText: "12",
      badgeColor: theme.colors.fgDanger,
      onPressed: () => context.router.push(const OrdersRoute()),
    ),
  ],
  child: const AutoRouter(),
),

​
Properties

​
Required

​
sidebarChildren
List<Widget>
required
The list of widgets to display in the sidebar. While you have full flexibility, most of the time this will be NeoSidebarButton widgets. You can also include other widgets like a logo, workspace dropdown, progress card, etc.
​
child
Widget
required
The main content widget that will be displayed alongside the sidebar. Typically const AutoRouter() when using Neo’s recommended routing approach, but can be any widget that represents your main content area.

​
State Management

The sidebar layout uses Riverpod providers to manage its state:
​
neoCurrentSidebarStatesProvider
StateNotifierProvider
Controls the sidebar’s visibility and collapse state. Access via ref.watch() or ref.read().

​
Available State Methods

// Collapse the sidebar
ref.read(neoCurrentSidebarStatesProvider.notifier).setCollapsed(true);

// Expand the sidebar
ref.read(neoCurrentSidebarStatesProvider.notifier).setCollapsed(false);

​
Platform Behavior

  • Swipe gestures: Control collapse/expand state
  • Content behavior: Main content area scales horizontally when collapsing/expanding
  • Swipe gestures: Control hide/show state
  • Content behavior: Content slides slightly offscreen to make room for sidebar

​
Animation & Theming

The sidebar layout uses smooth animations powered by the Neo Theming System:
​
theme.durations.sidebar
Duration
Controls the animation duration for sidebar transitions. Configurable through your theme, though the default timing is carefully crafted.

​
Best Practices

  • Recommended with AutoRouter: Use child: const AutoRouter() for nested routing when using Neo’s CLI templates and routing approach.
  • Safe area handling: Structure your pages with Container(color: theme.colors.bgPrimary) → NeoSafeArea → your content for proper full-screen behavior.
  • Active State Management: Determine active sidebar buttons based on your current route path. Use router.currentPath to check the active route and set isActive on NeoSidebarButton accordingly. See the Neo CLI sidebar template for a complete example.

​
Integration Notes

  • Internal Components: Never use NeoSidebar directly; NeoSidebarLayout handles everything and provides the complete Neo experience.
  • Safe Area Intelligence: Automatically handles safe areas and removes them during full-screen transitions.
  • Route-Based Active State: The sidebar no longer manages active item state internally. Instead, determine active state based on your routing system (e.g., using AutoRouter.currentPath).
Last modified on November 21, 2025