✨ Features #

🚀 Getting started #

Add to your pubspec.yaml:

dependencies:
  staggered_menu_flutter: ^0.0.3

Then run:

flutter pub get

🔨 Usage #

Minimal #

import 'package:staggered_menu_flutter/staggered_menu_flutter.dart';

StaggeredMenu(
  items: [
    StaggeredMenuItem(label: 'Home',    onTap: () {}),
    StaggeredMenuItem(label: 'About',   onTap: () {}),
    StaggeredMenuItem(label: 'Contact', onTap: () {}),
  ],
  child: Scaffold(
    body: Center(child: Text('My App')),
  ),
)

With all options #

StaggeredMenu(
  position: MenuPosition.right,   // or MenuPosition.left
  theme: StaggeredMenuThemeData(
    accentColor:      Color(0xFFFF2D55),
    preLayerColors:   [Color(0xFFFFC2D1), Color(0xFFFF2D55)],
    panelColor:       Colors.white,
    panelOpacity:     0.93,
    blurSigma:        16,
    barrierColor:     Color(0x44000000),
    showItemNumbering: true,
    enableHoverEffects: true,
    duration:         Duration(milliseconds: 800),
    panelCurve:       Curves.easeOutQuart,
  ),
  logo: Text(
    'STUDIO',
    style: TextStyle(color: Colors.white, fontWeight: FontWeight.w800),
  ),
  items: [
    StaggeredMenuItem(label: 'Home',     onTap: () {}),
    StaggeredMenuItem(label: 'Work',     onTap: () {}),
    StaggeredMenuItem(label: 'About',    onTap: () {}),
    StaggeredMenuItem(label: 'Contact',  onTap: () {}),
  ],
  socialItems: [
    StaggeredSocialItem(label: 'GitHub',   onTap: () {}),
    StaggeredSocialItem(label: 'Dribbble', onTap: () {}),
    StaggeredSocialItem(label: 'X',        onTap: () {}),
  ],
  onMenuOpen:  () => print('opened'),
  onMenuClose: () => print('closed'),
  child: Scaffold(
    backgroundColor: Color(0xFF0E0E12),
    body: Center(child: Text('Hello')),
  ),
)

� Controller #

Open, close, or toggle the menu from code:

final controller = StaggeredMenuController();

StaggeredMenu(
  controller: controller,
  items: [ /* … */ ],
  child: myScaffold,
);

// Later:
controller.open();
controller.close();
controller.toggle();

// Dispose when done:
controller.dispose();

🎨 Inherited theme #

Wrap a subtree with StaggeredMenuTheme to avoid passing theme: to every menu:

StaggeredMenuTheme(
  data: StaggeredMenuThemeData(accentColor: Colors.red),
  child: MaterialApp(home: MyPage()),
)

Resolution order: explicit theme parameter → nearest StaggeredMenuTheme → built-in defaults.

🛤 Named routes integration #

StaggeredMenu(
  items: StaggeredRouteHelper.fromRoutes(
    context,
    routes: {
      '/':        'Home',
      '/about':   'About',
      '/contact': 'Contact',
    },
    currentRoute: ModalRoute.of(context)?.settings.name,
  ),
  child: myScaffold,
)

The active route automatically gets a null onTap (disabled).

🧩 Custom item builder #

Replace the default uppercase-label rendering while keeping the stagger animation:

StaggeredMenu(
  itemBuilder: (context, item, index, hovered) {
    return Text(
      item.label,
      style: TextStyle(color: hovered ? Colors.red : Colors.white),
    );
  },
  items: [ /* … */ ],
  child: myScaffold,
)

⌨️ Keyboard navigation #

When the menu overlay is open:

• A FocusScope traps focus within the panel.
• Pressing Escape closes the menu.

No extra setup required — it works out of the box.

�🎨 Theming reference #

All properties have sensible defaults — override only what you need using copyWith:

const StaggeredMenuThemeData().copyWith(
  accentColor: Colors.deepPurple,
  blurSigma:   20,
  duration:    Duration(milliseconds: 600),
)

📁 Package structure #

staggered_menu_flutter/
├── lib/
│   ├── staggered_menu_flutter.dart   ← public barrel (import this)
│   └── src/
│       ├── controller.dart           ← StaggeredMenuController
│       ├── menu_theme.dart           ← StaggeredMenuTheme (InheritedWidget)
│       ├── models.dart               ← StaggeredMenuItem, StaggeredSocialItem, MenuPosition
│       ├── route_helper.dart         ← StaggeredRouteHelper
│       ├── theme.dart                ← StaggeredMenuThemeData
│       └── staggered_menu.dart       ← StaggeredMenu widget + itemBuilder + keyboard nav
├── example/
│   └── lib/main.dart                 ← runnable demo
├── test/
│   └── staggered_menu_flutter_test.dart  (33 tests)
├── CHANGELOG.md
├── LICENSE
└── pubspec.yaml

🧪 Running tests #

flutter test

🗺 Roadmap #

• ✅ StaggeredMenuController for programmatic open/close
• ✅ Named routes integration helper (StaggeredRouteHelper)
• ✅ StaggeredMenuTheme inherited widget
• ✅ Custom item builder slot (itemBuilder)
• ✅ Keyboard navigation (focus trap + Escape)

Upcoming:

• ❌ RTL layout support
• ❌ Spring physics animation preset
• ❌ Built-in hero transition for page changes

🤝 Contributing #

PRs and issues are welcome at github.com/NexivaServices/staggered_menu_flutter!
Please open an issue before submitting a large change so we can discuss the approach.

1. Fork the repository
2. Create your feature branch (git checkout -b feat/my-feature)
3. Commit your changes (git commit -m 'feat: add my feature')
4. Push to the branch (git push origin feat/my-feature)
5. Open a Pull Request

📄 License #

MIT © 2026 — see LICENSE for details.