WPopover

A flexible popover component for creating dropdown menus, notification panels, user menus, tooltips, and similar overlay patterns.

• Basic Usage
• Constructor
• Props
• Layout Modes
• Event Handling
• State Variants
• Styling Examples
• All Supported Classes
• Customizing Theme
• Related Documentation

WPopover(
  alignment: PopoverAlignment.bottomRight,
  className: 'w-64 bg-white dark:bg-gray-800 rounded-xl shadow-xl p-2',
  triggerBuilder: (context, isOpen, isHovering) => WButton(
    className: 'bg-blue-600 text-white',
    child: Text('Open Menu'),
  ),
  contentBuilder: (context, close) => Column(
    mainAxisSize: MainAxisSize.min,
    children: [
      ListTile(title: Text('Profile'), onTap: close),
      ListTile(title: Text('Settings'), onTap: close),
    ],
  ),
)

Basic Usage

The WPopover widget uses two builders: triggerBuilder for the element that activates the popover, and contentBuilder for the overlay content. It manages the overlay state and positioning automatically.

WPopover(
  triggerBuilder: (context, isOpen, isHovering) => WText(
    'Click me',
    className: 'text-blue-500 cursor-pointer',
  ),
  contentBuilder: (context, close) => WDiv(
    className: 'p-4',
    child: WText('Hello from Popover!'),
  ),
)

Constructor

const WPopover({
  Key? key,
  required PopoverTriggerBuilder triggerBuilder,
  required PopoverContentBuilder contentBuilder,
  PopoverController? controller,
  bool enableTriggerOnTap = true,
  PopoverAlignment alignment = PopoverAlignment.bottomLeft,
  String? className,
  Offset offset = const Offset(0, 4),
  double maxHeight = 400,
  double? width,
  double? maxWidth,
  bool disabled = false,
  bool closeOnContentTap = false,
  VoidCallback? onOpen,
  VoidCallback? onClose,
  bool autoFlip = true,
})

Props

Layout Modes

While WPopover itself isn't a layout container, it supports various Alignment Modes to determine how the overlay is positioned relative to the trigger.

Alignment

WPopover intelligently "flips" the alignment if the requested position would cause the overlay to overflow the screen edges. When neither side has room for maxHeight, it keeps the roomier side and shrinks to the space there, 8 pixels short of the edge, so a tall menu scrolls instead of running off a small window. The content has to be able to scroll for that: give the popover overflow-y-auto (or build the content on a scroll view), or a plain column overflows once capped.

Event Handling

The triggerBuilder provides the isOpen and isHovering states, allowing you to reactively style the trigger. The contentBuilder provides a close callback to dismiss the popover from within the content (e.g., when a menu item is clicked).

When enableTriggerOnTap is true (the default), tapping the trigger toggles the popover, and this works even when the trigger is an interactive widget that owns its own onTap (a WButton or WAnchor): the trigger's own callback and the popover toggle both fire on the same tap. Set enableTriggerOnTap: false for manual control via a PopoverController.

WPopover(
  triggerBuilder: (context, isOpen, isHovering) => WDiv(
    className: 'p-2 rounded ${isOpen ? "bg-blue-100" : "bg-gray-100"}',
    child: WText(isOpen ? 'Active' : 'Idle'),
  ),
  contentBuilder: (context, close) => WButton(
    onTap: close,
    child: Text('Click to Close'),
  ),
)

Keyboard

The trigger is one Tab stop. Enter, Space, and the Android TV D-pad centre toggle the popover, through the same ActivateIntent a WAnchor answers, so the keys follow whatever the platform binds to activation. Escape closes an open popover from the trigger or from anything focused inside the panel, returns focus to the trigger, and stops there: one press closes the popover and not also the dialog or sheet holding it, and a page pushed over an open popover keeps its own Escape. While the popover is closed, Escape is left alone and reaches the app's own shortcuts, so a dialog holding a popover still closes on it. After a keyboard open, focus stays on the trigger even on the web, where the browser drops it as the panel mounts. The trigger and the panel form one traversal group in widget order, so the next Tab moves into the panel, top to bottom, whether it opened below the trigger or flipped above it, and Tab past its last control leaves the popover.

A disabled popover is not a Tab stop. With enableTriggerOnTap: false, Enter and Space do nothing, as a tap does nothing; Escape still closes a popover the controller opened.

State Variants

Since the popover trigger is built via triggerBuilder, you can apply state-based styling manually or use Wind's state prefixes if the trigger is a Wind widget like WButton or WDiv.

The popover publishes its trigger's interaction state the way a WAnchor does, so a plain WDiv trigger answers hover:, focus: and disabled: without an anchor of its own. Give the trigger a focus: class, or a keyboard user cannot see where focus is:

WPopover(
  triggerBuilder: (context, isOpen, isHovering) => WDiv(
    className: '''
      p-2 rounded-lg bg-white dark:bg-gray-800
      focus:ring-2 focus:ring-blue-500
    ''',
    child: WIcon(Icons.notifications_outlined),
  ),
  contentBuilder: (context, close) => MyContent(),
)

WPopover(
  triggerBuilder: (context, isOpen, isHovering) => WButton(
    // Use the isOpen boolean for manual state toggling
    className: 'p-2 rounded-lg ${isOpen ? "bg-blue-600 text-white" : "bg-white text-gray-800"}',
    child: Text('Toggle Menu'),
  ),
  contentBuilder: (context, close) => MyContent(),
)

Styling Examples

Custom Size and Shadow

If no width is specified in className, the popover uses the trigger's width as a minimum. Use sizing utilities to define a specific width.

WPopover(
  className: 'w-80 bg-white rounded-2xl shadow-2xl border border-gray-100',
  triggerBuilder: (context, isOpen, isHovering) => Icon(Icons.more_horiz),
  contentBuilder: (context, close) => MyLargeMenu(),
)

Dark Mode

WPopover fully supports dark mode styling using the dark: prefix.

WPopover(
  className: 'bg-white dark:bg-gray-900 border-gray-200 dark:border-gray-800 shadow-xl',
  triggerBuilder: (context, isOpen, isHovering) => MyTrigger(),
  contentBuilder: (context, close) => MyContent(),
)

All Supported Classes

The popover overlay container is a WDiv and supports all standard Wind utilities.

Customizing Theme

Popovers inherit from global theme scales. You can customize the default appearance by modifying the WindThemeData.

WindThemeData(
  colors: {
    'popover-bg': Colors.white,
  },
  baseSpacingUnit: 4.0,
)

Related Documentation

• WSelect - A high-level dropdown built using WPopover
• WDiv - The base container widget
• WAnchor - Useful for interactive elements inside the popover