Understanding Flutter PopupMenuButton: A Detailed Guide

In Flutter, creating rich, interactive user interfaces is easy thanks to its flexible and widget-centric architecture. One of the widgets that provide a simple way to display menus or options in a pop-up style is the PopupMenuButton. This widget allows you to show a list of choices in a context-sensitive menu when the user taps a button or area of the screen. This is often used for options, settings, or navigation menus in your app.

What is a `PopupMenuButton`?

PopupMenuButton is a Flutter widget that creates a button which, when pressed, displays a menu of options (a "popup" menu) from which the user can select. The menu typically appears below or above the button, depending on the space available.

This is ideal for use cases such as:

Showing additional options like settings, actions, or context-sensitive menus.
Providing a compact way to display multiple actions without cluttering the UI.
Presenting a list of items that require user selection, such as deleting or sharing content.

Basic Structure of a `PopupMenuButton`

Here’s a simple example of the structure:

PopupMenuButton<String>(
  onSelected: (value) {
    // Handle the selected value
  },
  itemBuilder: (BuildContext context) {
    return [
      PopupMenuItem<String>(
        value: 'Option 1',
        child: Text('Option 1'),
      ),
      PopupMenuItem<String>(
        value: 'Option 2',
        child: Text('Option 2'),
      ),
      PopupMenuItem<String>(
        value: 'Option 3',
        child: Text('Option 3'),
      ),
    ];
  },
)

In this example:

onSelected: A callback that receives the selected value.
itemBuilder: This builder function returns a list of PopupMenuItem widgets, each representing a menu option.

Constructor of `PopupMenuButton`

The constructor of PopupMenuButton is designed to create a button that triggers a menu when pressed. Here’s a simple structure of the constructor:

PopupMenuButton<T>({
  Key? key,
  required this.onSelected,
  required this.itemBuilder,
  this.icon = const Icon(Icons.more_vert),
  this.iconSize = 24.0,
  this.elevation = 8.0,
  this.color,
  this.padding = const EdgeInsets.all(8.0),
  this.offset,
  this.tooltip = 'Show options',
  this.enabled = true,
  this.initialValue,
  this.shape,
  this.contextMenuBuilder,
})

Explanation of Constructor Parameters:

Key? key:
An optional parameter used to uniquely identify this widget in the widget tree. This is generally used when managing state in complex trees or lists. Most of the time, you can omit it.
required this.onSelected:
A required callback function that handles the action when the user selects a menu item. It receives the value passed to the selected PopupMenuItem widget. For example, if you select an option like "Profile", it will pass that value to the callback.
Example:
```
onSelected: (String value) {
  print('You selected: $value');
}
```
required this.itemBuilder:
A required function that returns a list of PopupMenuItem widgets that will be displayed in the popup menu. This function should return a list of items that represent the menu options.
Example:
```
itemBuilder: (BuildContext context) => [
  PopupMenuItem<String>(value: 'Option 1', child: Text('Option 1')),
  PopupMenuItem<String>(value: 'Option 2', child: Text('Option 2')),
]
```
this.icon = const Icon(Icons.more_vert):
The icon displayed on the button that triggers the menu. The default icon is Icons.more_vert (three vertical dots), but you can change it to any other Icon widget or Image.
Example:
```
icon: Icon(Icons.settings),
```
this.iconSize = 24.0:
The size of the icon in pixels. By default, the size is 24.0, but you can increase or decrease it according to your design.
Example:
```
iconSize: 30.0,  // Makes the icon larger
```
this.elevation = 8.0:
Controls the elevation (shadow) of the popup menu. Higher values give the menu a more prominent shadow effect. By default, it is set to 8.0, but you can reduce it for a flatter appearance.
Example:
```
elevation: 12.0,  // Adds more shadow
```
this.color:
The background color of the popup menu. If not provided, the menu will have the default theme-based color (usually white). You can change it to any color.
Example:
```
color: Colors.blueAccent,
```
this.padding = const EdgeInsets.all(8.0):
Padding around the icon button. By default, there is 8.0 units of padding around the button, but you can customize it if you need more space or less.
Example:
```
padding: EdgeInsets.symmetric(horizontal: 12.0),
```
this.offset:
The offset is used to define the position of the popup menu relative to the button. You can change the default placement of the menu (usually below or above the button) by using this property. The offset is in the form of an Offset object, which takes dx (horizontal distance) and dy (vertical distance).
Example:
```
offset: Offset(0, 50),  // Moves the menu 50 pixels down
```
this.tooltip = 'Show options':
The tooltip text that appears when the user long presses the PopupMenuButton. This provides additional context about the button’s purpose. By default, the tooltip is set to "Show options".
Example:
```
tooltip: 'More actions',  // Custom tooltip text
```
this.enabled = true:
Whether the button should be enabled or disabled. If set to false, the button will not trigger the popup menu, and the user cannot interact with it.
Example:
```
enabled: false,  // Disables the button
```
this.initialValue:
A value that can be set to the initial state of the menu before it is displayed. This is useful if you want to pre-select a value in the menu or show a default selection. It is commonly used with forms or when the initial state is important.
Example:
```
initialValue: 'Option 1',  // Pre-selects a default option
```
this.shape:
The shape of the popup menu. You can customize the border shape of the menu (e.g., rounded corners or a specific shape).
Example:
```
shape: RoundedRectangleBorder(
  borderRadius: BorderRadius.circular(12.0),
),
```
this.contextMenuBuilder:
An optional function that can be used to build a custom context menu for the button. This can be helpful when you need a more complex menu that isn't just a list of items but rather a fully customized widget. This property is useful when the built-in itemBuilder is not enough.
Example:
```
contextMenuBuilder: (BuildContext context) {
  return CustomContextMenu(); // Return a custom widget
},
```

Recap of the Properties

onSelected: Callback when an item is selected.
itemBuilder: Builds the list of PopupMenuItem widgets.
icon: The icon displayed for the button.
iconSize: Size of the icon.
elevation: Elevation (shadow) of the popup menu.
color: Background color of the popup menu.
padding: Padding around the icon.
offset: Position of the popup relative to the button.
tooltip: Tooltip text that appears on long press.
enabled: Whether the button is enabled or disabled.
initialValue: Initial value of the menu.
shape: The shape of the popup menu.
contextMenuBuilder: Custom function for building context menus.

Example with Multiple Properties:

PopupMenuButton<String>(
  onSelected: (String value) {
    print('You selected: $value');
  },
  itemBuilder: (BuildContext context) => [
    PopupMenuItem<String>(value: 'Profile', child: Text('Profile')),
    PopupMenuItem<String>(value: 'Settings', child: Text('Settings')),
    PopupMenuItem<String>(value: 'Logout', child: Text('Logout')),
  ],
  icon: Icon(Icons.account_circle),
  iconSize: 30.0,
  elevation: 12.0,
  color: Colors.blueAccent,
  padding: EdgeInsets.symmetric(horizontal: 10.0),
  offset: Offset(0, 50),
  tooltip: 'Tap for more options',
  enabled: true,
  initialValue: 'Settings',
  shape: RoundedRectangleBorder(
    borderRadius: BorderRadius.circular(10.0),
  ),
)

In this example, we’ve used a variety of properties to customize the appearance and behavior of the PopupMenuButton:

A custom icon (Icons.account_circle).
Increased icon size (30.0).
Custom background color (Colors.blueAccent).
Offset to move the popup 50 pixels down.
Rounded corners for the popup menu (borderRadius).

Conclusion

The PopupMenuButton widget is a powerful tool for creating dynamic menus in Flutter. It is highly customizable, allowing developers to build rich, interactive UIs with minimal effort. Whether you need a simple settings menu or a complex contextual action menu, this widget can help streamline your app’s design and user experience.

By using the properties like icon, onSelected, itemBuilder, and others, you can create a pop-up menu that fits your app's style and functionality needs.

Hopefully, this blog has provided you with a detailed understanding of the PopupMenuButton in Flutter.

Happy coding! 🚀

Search This Blog

Flutter Blogs