flutter_show_menu #

A drop-in replacement for Flutter's built-in showMenu using OverlayEntry.

Position menus relative to any widget with full control over direction, alignment, animation, and styling.

Features #

• OverlayEntry-based — no Navigator route pushed, no context limitations
• Directional positioning — place the menu on top, bottom, left, or right of the target
• Cross-axis alignment — align start, center, or end along the opposite axis
• Auto flip — automatically flips to the opposite side when overflowing the screen edge
• Smooth animation — fade + scale with configurable duration and curve
• Two API styles — imperative function (showOverlayMenu) and declarative widget (OverlayMenuButton)
• Barrier support — dismiss on outside tap with optional backdrop color
• Rich styling — OverlayMenuStyle with grouped sub-classes for item, selected, divider, and scrollbar styles
• Divider support — OverlayMenuDivider entries between items
• Selected state — per-item selected flag with customizable background, text style, and border
• Prefix builder — per-item or style-level leading widget with selected state awareness
• Scrollable menu — maxHeight with automatic scrolling and scrollbar theming
• Auto-scroll to selected — when reopening a scrollable menu, the selected item is automatically centered in the viewport
• Header / Footer — fixed entries pinned above/below the scrollable area with independent styling
• Auto-close on navigation — menu automatically dismisses when the route is popped or a new route is pushed
• Overlay child — full-screen overlay above the barrier (e.g. drag-to-move area)
• Programmatic close — OverlayMenuController for explicit dismissal with safe idempotent close()

Install #

dependencies:
  flutter_show_menu: ^0.4.1

Basic Usage #

Imperative — showOverlayMenu #

import 'package:flutter_show_menu/flutter_show_menu.dart';

final result = await showOverlayMenu<String>(
  context: context,
  items: [
    OverlayMenuItem(value: 'edit', child: Text('Edit')),
    OverlayMenuItem(value: 'delete', child: Text('Delete')),
  ],
  position: MenuPosition.bottom,
  alignment: MenuAlignment.start,
);

if (result != null) {
  print('Selected: $result');
}

Declarative — OverlayMenuButton #

OverlayMenuButton<String>(
  position: MenuPosition.right,
  alignment: MenuAlignment.center,
  items: [
    OverlayMenuItem(value: 'edit', child: Text('Edit')),
    OverlayMenuItem(value: 'share', child: Text('Share')),
    OverlayMenuItem(value: 'delete', child: Text('Delete')),
  ],
  onSelected: (value) => print('Selected: $value'),
  onCanceled: () => print('Dismissed'),
  child: Icon(Icons.more_vert),
)

With Styling, Dividers, and Selected State #

final result = await showOverlayMenu<String>(
  context: context,
  items: [
    OverlayMenuItem(value: 'home', selected: true, child: Text('Home')),
    OverlayMenuDivider(),
    OverlayMenuItem(value: 'settings', child: Text('Settings')),
    OverlayMenuItem(value: 'logout', child: Text('Logout')),
  ],
  style: OverlayMenuStyle(
    backgroundColor: Colors.white,
    borderRadius: BorderRadius.circular(12),
    maxHeight: 300,
    itemStyle: OverlayMenuItemStyle(
      height: 44,
      borderRadius: BorderRadius.circular(8),
      padding: EdgeInsets.symmetric(horizontal: 12),
      hoverColor: Colors.blue.withValues(alpha: 0.08),
    ),
    selectedStyle: OverlayMenuSelectedStyle(
      backgroundColor: Colors.blue.withValues(alpha: 0.12),
      textStyle: TextStyle(fontWeight: FontWeight.w600, color: Colors.blue),
    ),
    dividerStyle: OverlayMenuDividerStyle(color: Colors.grey.shade300),
    prefixBuilder: (context, selected) => Icon(
      selected ? Icons.check_circle : Icons.circle_outlined,
      size: 20,
    ),
  ),
);

With Header and Footer #

final result = await showOverlayMenu<String>(
  context: context,
  header: [
    OverlayMenuItem(value: 'search', child: Text('Search...')),
    OverlayMenuDivider(),
  ],
  items: [
    OverlayMenuItem(value: 'home', child: Text('Home')),
    OverlayMenuItem(value: 'settings', child: Text('Settings')),
    OverlayMenuItem(value: 'profile', child: Text('Profile')),
  ],
  footer: [
    OverlayMenuDivider(),
    OverlayMenuItem(value: 'create', child: Text('Create New')),
  ],
  style: OverlayMenuStyle(
    maxHeight: 250,
    headerStyle: OverlayMenuHeaderStyle(height: 40),
    footerStyle: OverlayMenuFooterStyle(height: 40),
  ),
);

Position & Alignment #

MenuPosition determines which side of the target the menu appears on. MenuAlignment determines how the menu is aligned on the cross axis.

            start   center    end
              ↓       ↓        ↓
            ┌──────────────────────┐
            │     top menu         │
            └──────────────────────┘
            ┌──────────────────────┐
left menu   │     Target Widget    │   right menu
            └──────────────────────┘
            ┌──────────────────────┐
            │    bottom menu       │
            └──────────────────────┘

When the menu overflows the screen edge, it automatically flips to the opposite side.

API Reference #

showOverlayMenu<T> #

Returns Future<T?> — the selected item's value, or null if dismissed.

OverlayMenuController #

Controller for programmatically closing an open menu. Safe to call close() multiple times.

final controller = OverlayMenuController();

showOverlayMenu<String>(
  context: context,
  items: [...],
  controller: controller,
);

// Later — safe even if the menu was already dismissed:
controller.close();

Note: The menu also auto-closes when the current route is popped or a new route is pushed on top — no controller needed for navigation scenarios.

OverlayMenuButton<T> #

A widget that wraps a child and shows an overlay menu on tap.

OverlayMenuEntry<T> (sealed) #

Base type for menu entries. Two subtypes:

OverlayMenuItem<T>

OverlayMenuDivider<T>

OverlayMenuStyle #

OverlayMenuItemStyle #

OverlayMenuSelectedStyle #

OverlayMenuDividerStyle #

OverlayMenuHeaderStyle / OverlayMenuFooterStyle #

Type aliases for OverlayMenuItemStyle. Same parameters as OverlayMenuItemStyle above.

OverlayMenuScrollbarStyle #

MenuPosition #

MenuAlignment #

Example #

The example/ directory contains a playground app where you can interactively test all parameters — position, alignment, offset, styling, animation, and theme.

cd example
flutter run