PopupMenuButton<T> class

Displays a menu when pressed and calls onSelected when the menu is dismissed because an item was selected. The value passed to onSelected is the value of the selected menu item.

One of child or icon may be provided, but not both. If icon is provided, then PopupMenuButton behaves like an IconButton.

If both are null, then a standard overflow icon is created (depending on the platform).

Updating to MenuAnchor

There is a Material 3 component, MenuAnchor that is preferred for applications that are configured for Material 3 (see ThemeData.useMaterial3). The MenuAnchor widget's visuals are a little bit different, see the Material 3 spec at m3.material.io/components/menus/guidelines for more details.

The MenuAnchor widget's API is also slightly different. MenuAnchor's were built to be lower level interface for creating menus that are displayed from an anchor.

There are a few steps you would take to migrate from PopupMenuButton to MenuAnchor:

Instead of using the PopupMenuButton.itemBuilder to build a list of PopupMenuEntrys, you would use the MenuAnchor.menuChildren which takes a list of Widgets. Usually, you would use a list of MenuItemButtons as shown in the example below.
Instead of using the PopupMenuButton.onSelected callback, you would set individual callbacks for each of the MenuItemButtons using the MenuItemButton.onPressed property.
To anchor the MenuAnchor to a widget, you would use the MenuAnchor.builder to return the widget of choice - usually a TextButton or an IconButton.
You may want to style the MenuItemButtons, see the MenuItemButton documentation for details.

Use the sample below for an example of migrating from PopupMenuButton to MenuAnchor.

This example shows a menu with three items, selecting between an enum's values and setting a selectedMenu field based on the selection.

To create a local project with this code sample, run:
flutter create --sample=material.PopupMenuButton.1 mysample

This example shows how to migrate the above to a MenuAnchor.

To create a local project with this code sample, run:
flutter create --sample=material.PopupMenuButton.2 mysample

This sample shows the creation of a popup menu, as described in: https://m3.material.io/components/menus/overview

To create a local project with this code sample, run:
flutter create --sample=material.PopupMenuButton.3 mysample

This sample showcases how to override the PopupMenuButton animation curves and duration using AnimationStyle.

To create a local project with this code sample, run:
flutter create --sample=material.PopupMenuButton.4 mysample

Constructors

PopupMenuButton({Key? key, required PopupMenuItemBuilder<T> itemBuilder, T? initialValue, VoidCallback? onOpened, PopupMenuItemSelected<T>? onSelected, PopupMenuCanceled? onCanceled, String? tooltip, double? elevation, Color? shadowColor, Color? surfaceTintColor, EdgeInsetsGeometry padding = const EdgeInsets.all(8.0), EdgeInsetsGeometry? menuPadding, Widget? child, double? splashRadius, Widget? icon, double? iconSize, Offset offset = Offset.zero, bool enabled = true, ShapeBorder? shape, Color? color, Color? iconColor, bool? enableFeedback, BoxConstraints? constraints, PopupMenuPosition? position, Clip clipBehavior = Clip.none, bool useRootNavigator = false, AnimationStyle? popUpAnimationStyle, RouteSettings? routeSettings, ButtonStyle? style}): Creates a button that shows a popup menu.
const

Properties

child → Widget?: If provided, child is the widget used for this button and the button will utilize an InkWell for taps.
final
clipBehavior → Clip: The content will be clipped (or not) according to this option.
final
color → Color?: If provided, the background color used for the menu.
final
constraints → BoxConstraints?: Optional size constraints for the menu.
final
elevation → double?: The z-coordinate at which to place the menu when open. This controls the size of the shadow below the menu.
final
enabled → bool: Whether this popup menu button is interactive.
final
enableFeedback → bool?: Whether detected gestures should provide acoustic and/or haptic feedback.
final
hashCode → int: The hash code for this object.
no setterinherited
icon → Widget?: If provided, the icon is used for this button and the button will behave like an IconButton.
final
iconColor → Color?: If provided, this color is used for the button icon.
final
iconSize → double?: If provided, the size of the Icon.
final
initialValue → T?: The value of the menu item, if any, that should be highlighted when the menu opens.
final
itemBuilder → PopupMenuItemBuilder<T>: Called when the button is pressed to create the items to show in the menu.
final
key → Key?: Controls how one widget replaces another widget in the tree.
finalinherited
menuPadding → EdgeInsetsGeometry?: If provided, menu padding is used for empty space around the outside of the popup menu.
final
offset → Offset: The offset is applied relative to the initial position set by the position.
final
onCanceled → PopupMenuCanceled?: Called when the user dismisses the popup menu without selecting an item.
final
onOpened → VoidCallback?: Called when the popup menu is shown.
final
onSelected → PopupMenuItemSelected<T>?: Called when the user selects a value from the popup menu created by this button.
final
padding → EdgeInsetsGeometry: Matches IconButton's 8 dps padding by default. In some cases, notably where this button appears as the trailing element of a list item, it's useful to be able to set the padding to zero.
final
popUpAnimationStyle → AnimationStyle?: Used to override the default animation curves and durations of the popup menu's open and close transitions.
final
position → PopupMenuPosition?: Whether the popup menu is positioned over or under the popup menu button.
final
routeSettings → RouteSettings?: Optional route settings for the menu.
final
runtimeType → Type: A representation of the runtime type of the object.
no setterinherited
shadowColor → Color?: The color used to paint the shadow below the menu.
final
shape → ShapeBorder?: If provided, the shape used for the menu.
final
splashRadius → double?: The splash radius.
final
style → ButtonStyle?: Customizes this icon button's appearance.
final
surfaceTintColor → Color?: The color used as an overlay on color to indicate elevation.
final
tooltip → String?: Text that describes the action that will occur when the button is pressed.
final
useRootNavigator → bool: Used to determine whether to push the menu to the Navigator furthest from or nearest to the given context.
final

Methods

createElement() → StatefulElement: Creates a StatefulElement to manage this widget's location in the tree.
inherited
createState() → PopupMenuButtonState<T>: Creates the mutable state for this widget at a given location in the tree.
override
debugDescribeChildren() → List<DiagnosticsNode>: Returns a list of DiagnosticsNode objects describing this node's children.
inherited
debugFillProperties(DiagnosticPropertiesBuilder properties) → void: Add additional properties associated with the node.
inherited
noSuchMethod(Invocation invocation) → dynamic: Invoked when a nonexistent method or property is accessed.
inherited
toDiagnosticsNode({String? name, DiagnosticsTreeStyle? style}) → DiagnosticsNode: Returns a debug representation of the object that is used by debugging tools and by DiagnosticsNode.toStringDeep.
inherited
toString({DiagnosticLevel minLevel = DiagnosticLevel.info}) → String: A string representation of this object.
inherited
toStringDeep({String prefixLineOne = '', String? prefixOtherLines, DiagnosticLevel minLevel = DiagnosticLevel.debug}) → String: Returns a string representation of this node and its descendants.
inherited
toStringShallow({String joiner = ', ', DiagnosticLevel minLevel = DiagnosticLevel.debug}) → String: Returns a one-line detailed description of the object.
inherited
toStringShort() → String: A short, textual description of this widget.
inherited

Operators

operator ==(Object other) → bool: The equality operator.
inherited