Flutter Dialogs: A Step-by-Step Guide

A screen sometimes needs to offer a choice without sending the user to another page. A Flutter dialog displays a temporary message or set of options above the current screen.

I’ll show how to present choices with SimpleDialog and handle the result, including when the dialog closes without a selection.

What are Flutter dialogs?

A dialog is a temporary Material interface shown above the current route. showDialog pushes a route to display it, and its builder creates the dialog content.

The route result is a Future, and calling Navigator.pop with a value completes it for the code that opened the dialog. Use AlertDialog for a message with actions or SimpleDialog when the reader needs to choose an option.

Prerequisites

The examples need MaterialApp and an import for package:flutter/material.dart. If Flutter is not set up, follow the Flutter setup guide.

• A Flutter app with MaterialApp in its widget tree
• A button callback whose BuildContext belongs to that app
• package:flutter/material.dart imported in the Dart file

Each example opens the route from a button callback under MaterialApp. Inside the builder, close that route with its dialog context rather than reusing the caller context.

Step 1: Show an AlertDialog from a button

For a confirmation, return a boolean from each action and let the caller decide whether to continue. The dialog route carries that result back to the button handler.

Future<void> confirmExit(BuildContext context, VoidCallback onConfirm) async {
  final shouldExit = await showDialog<bool>(
    context: context,
    builder: (dialogContext) => AlertDialog(
      title: const Text('Do you want to exit?'),
      actions: [
        TextButton(
          onPressed: () => Navigator.pop(dialogContext, false),
          child: const Text('No'),
        ),
        TextButton(
          onPressed: () => Navigator.pop(dialogContext, true),
          child: const Text('Yes'),
        ),
      ],
    ),
  );

  if (shouldExit == true) {
    onConfirm();
  }
}

showDialog<bool> makes the route result nullable, because tapping outside dismisses the dialog by default and returns null.

Checking for true means both No and outside dismissal leave the app untouched, while Yes returns true and runs the caller-provided callback.

Set barrierDismissible to false only when closing without an explicit choice would leave the task in an unsafe state. A confirmation dialog should still provide a clear cancel action.

Step 2: Offer choices with SimpleDialog

Use SimpleDialog when the user is picking one option rather than responding to a message. SimpleDialogOption calls Navigator.pop with the selected value, which completes the Future returned by showDialog.

enum DialogChoice { optionOne, optionTwo }

Future<DialogChoice?> chooseDialogOption(BuildContext context) {
  return showDialog<DialogChoice>(
    context: context,
    builder: (dialogContext) => SimpleDialog(
      title: const Text('Simple Dialog'),
      children: [
        SimpleDialogOption(
          onPressed: () =>
              Navigator.pop(dialogContext, DialogChoice.optionOne),
          child: const Text('Option One'),
        ),
        SimpleDialogOption(
          onPressed: () =>
              Navigator.pop(dialogContext, DialogChoice.optionTwo),
          child: const Text('Option Two'),
        ),
      ],
    ),
  );
}

The enum returns an explicit value, so the caller does not need to compare the displayed option text.

SimpleDialog handles scrolling for its choices, while the Future still resolves to null if the user dismisses the route without choosing.

Step 3: Handle the dialog result in the caller

Await the dialog where you opened it, then handle both a selected value and dismissal. The generic type on showDialog keeps the caller’s result aligned with the values passed to Navigator.pop.

Future<void> handleDialogChoice(BuildContext context) async {
  final choice = await chooseDialogOption(context);

  if (!context.mounted || choice == null) {
    return;
  }

  debugPrint('Selected option: $choice');
}

A null result means the route closed without a selection, so the handler returns without acting. The mounted check protects later context use if the caller leaves the widget tree while it waits.

Verify the dialog flow

Check the whole route cycle in the app, not only whether the dialog appears. Each button should produce one visible outcome in the page that opened it.

1. Tap the confirmation button and make sure the AlertDialog appears above the current screen.
2. Choose Cancel and confirm the delete branch does not run.
3. Choose Delete and confirm the caller receives true and runs its action.
4. Open the choice dialog, select each option, and confirm the caller receives the matching enum value.
5. Dismiss without choosing and confirm the caller handles null without acting.

When dismissal or layout surprises you

Dialog problems often come from route behavior or content sizing rather than the button widget. Check the matching boundary before changing the dialog’s design.

showDialog uses the root Navigator by default. An app with nested navigation may need to pop that same root route explicitly.

Let the dialog return a decision

A dialog works best when its result is part of the calling function’s control flow, rather than hidden inside a button callback. Give the route a result type, return one value for each action, and keep dismissal distinct from a choice.

final DialogChoice? choice = await chooseDialogOption(context);
if (choice == null) return;
debugPrint('Selected option: $choice');

Flutter dialog questions

showDialog pushes a route, so the dialog has its own builder context and returns its result to the code that opened it.