> ## Documentation Index
> Fetch the complete documentation index at: https://neo.tvk.company/llms.txt
> Use this file to discover all available pages before exploring further.

# Sidebar

> A responsive layout that provides a collapsible sidebar navigation with smooth animations and adaptive behavior.

<Tip>
  **Quick Setup with Neo CLI**: The easiest way to get started with the sidebar layout is using the [Neo CLI](/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.
</Tip>

## Example

<CodeGroup>
  ```dart Basic Usage lines theme={null}
  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(),
  ),
  ```
</CodeGroup>

## Properties

### Required

<ParamField path="sidebarChildren" type="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/buttons/sidebar-button) widgets. You can also include other widgets like a logo, workspace dropdown, progress card, etc.
</ParamField>

<ParamField path="child" type="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.
</ParamField>

## State Management

The sidebar layout uses Riverpod providers to manage its state:

<ParamField path="neoCurrentSidebarStatesProvider" type="StateNotifierProvider">
  Controls the sidebar's visibility and collapse state. Access via `ref.watch()` or `ref.read()`.
</ParamField>

### Available State Methods

<CodeGroup>
  ```dart Collapse/Expand lines theme={null}
  // Collapse the sidebar
  ref.read(neoCurrentSidebarStatesProvider.notifier).setCollapsed(true);

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

  ```dart Hide/Show lines theme={null}
  // Hide the sidebar
  ref.read(neoCurrentSidebarStatesProvider.notifier).setHidden(true);

  // Show the sidebar
  ref.read(neoCurrentSidebarStatesProvider.notifier).setHidden(false);
  ```

  ```dart Check Current State lines theme={null}
  final sidebarState = ref.watch(neoCurrentSidebarStatesProvider);
  final isCollapsed = sidebarState.isCollapsed;
  final isHidden = sidebarState.isHidden;
  final hideText = sidebarState.hideText;
  ```
</CodeGroup>

## Platform Behavior

<AccordionGroup>
  <Accordion title="Desktop (768px and above)">
    * **Swipe gestures**: Control collapse/expand state
    * **Content behavior**: Main content area scales horizontally when collapsing/expanding
  </Accordion>

  <Accordion title="Mobile (below 768px)">
    * **Swipe gestures**: Control hide/show state
    * **Content behavior**: Content slides slightly offscreen to make room for sidebar
  </Accordion>
</AccordionGroup>

## 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](/cli/templates/sidebar) 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`).