What is an alert dialog?

An alert dialog (also known as a basic dialog or simply an alert) informs the user about situations that require acknowledgment. An alert dialog has content, an optional title and an optional list of actions. The title is displayed above the content and the actions are displayed below the content.

Platform differences

Since Android 12, the default UI of alert dialogs follows the design guidelines defined in Material 3 (M3). On iOS, an equivalent component called “alert” is defined in Apple’s Human Interface Guidelines (HIG). There are some notable differences on the design of the alert dialog between the two platforms, as shown in the table below.

	Basic Dialog in M3	Alert in HIG
Platform Typography	Roboto	San Francisco
Container Color	Surface 3	#F2F2F2, 80%
Text button color	Primary	SystemBlue, SystemRed
Animation	Dialogs enter and exit the screen in a fade-transition pattern with an easeOut animation curve.	Alerts enter and exit the screen in a fade-transition pattern with an easeInOut curve.

The Flutter framework has two different widgets for displaying alert dialogs:

• AlertDialog, which implements the specification defined by Material Design.
• CupertinoAlertDialog, which follows the look & feel of the iOS default alert dialogs.

Adaptation recommendation

Our overall recommendation is to follow the platform convention when using alert dialogs in your app.

Rationale and exception

Since alert dialogs are often tightly integrated with the operating system, we recommend following the platform conventions. This is especially important when a dialog is used to request user input about security, privacy, and destructive operations (e.g., deleting files permanently). As an exception, a branded alert dialog design can be used on non-critical user flows to highlight specific information or messages. Here are some examples of alert dialog usage from public apps.

Lyft (System alert UI)	Medium (Branded alert UI)

This option has the following tradeoffs:

• User acceptance: High
• Amount of platform-specific code: Moderate
• Automated by Flutter: No
• Automatable by package: Yes

Example code

To implement platform-specific alert dialogs, you can use Flutter’s AlertDialog widget on Android and the CupertinoAlertDialog widget on iOS. Below is a code snippet you can adapt to show a platform-specific alert dialog. You can run this program in a local project to see the effect in action.

void _showAdaptiveDialog(
  context, {
  required Text title,
  required Text content,
  required List<Widget> actions,
}) {
  Platform.isIOS || Platform.isMacOS
      ? showCupertinoDialog<String>(
          context: context,
          builder: (BuildContext context) => CupertinoAlertDialog(
            title: title,
            content: content,
            actions: actions,
          ),
        )
      : showDialog(
          context: context,
          builder: (BuildContext context) => AlertDialog(
            title: title,
            content: content,
            actions: actions,
          ),
        );
}

Automated adaptation

A .adaptive constructor has been added to AlertDialog to enable automatic adaptation of the widget across platforms. See flutter/flutter#124336 for details. It will likely to be available in the next stable release of Flutter.