Ultimate Guide to Material 3 Dialogs in Android XML (2025 Tutorial + Examples)

Ultimate Guide to Material 3 Dialogs in Android: Tutorial & Examples for 2025 🚀

Overview 📖

Material 3 Dialogs are modal windows that interrupt app flow to provide critical information or prompt user decisions. This guide covers two variants—Basic and Full-screen—their implementation, and theming for 2025. 🔔

Design and API Documentation 🔗

• Google Material 3 Dialog Spec
• API Reference

Using Dialogs 🤖

Add the Material Components for Android library dependency to use Material 3 Dialogs. See the Get Started guide. Use MaterialAlertDialogBuilder for Basic dialogs or DialogFragment for Full-screen dialogs. Use a Theme.Material3.* theme for proper styling. 🛠️

Making Dialogs Accessible ♿

Set android:contentDescription on content, like title icons, for screen readers like TalkBack. Ensure buttons and interactive elements are focusable. See the Android accessibility guide. 🗣️

Behavior and Configuration 🎬

Configure dialogs with setTitle, setMessage, and button listeners (setPositiveButton, etc.). Use setView for custom content. Example:

      
MaterialAlertDialogBuilder(context)
    .setTitle("Confirm Action")
    .setMessage("Are you sure you want to proceed?")
    .setPositiveButton("OK") { _, _ -> /* Handle OK */ }
    .setNegativeButton("Cancel") { _, _ -> /* Handle Cancel */ }
    .show()
      
      
    

Dialog Variants 🌟

Material 3 Dialogs come in two variants: Basic (compact, for simple prompts) and Full-screen (for complex tasks). Each suits specific interaction needs. 🔔

1. Basic Dialog: For alerts or simple decisions.
2. Full-screen Dialog: For multi-step tasks, like form entry.

Basic Dialog 🔔

Basic Dialogs present critical information or prompt simple decisions, like confirming actions. 🔔

Basic Dialog Example 💻

API and source code:

• MaterialAlertDialogBuilder
  • Class description
  • Class source

The following example shows a basic dialog with three buttons.

      
MaterialAlertDialogBuilder(context)
    .setTitle(R.string.dialog_title)
    .setMessage(R.string.dialog_message)
    .setNeutralButton(R.string.cancel) { _, _ -> /* Handle cancel */ }
    .setNegativeButton(R.string.decline) { _, _ -> /* Handle decline */ }
    .setPositiveButton(R.string.accept) { _, _ -> /* Handle accept */ }
    .show()
      
      
    

Anatomy and Key Properties 📏

A basic dialog includes a container, optional title, content, buttons, and scrim. 🔔

• Container: Modal window, rounded corners.
• Title: Optional, describes the task. ✍️
• Content: Text or custom view, e.g., list. 📋
• Buttons: Up to three (neutral, negative, positive). 🖱️
• Scrim: Dims background, 32% opacity. 🌑

Full-screen Dialog 📺

Full-screen Dialogs cover the entire screen for complex tasks, like form entry, using DialogFragment. 📺

Full-screen Dialog Example 💻

The following example shows a full-screen dialog using DialogFragment with a dismiss button handler.

      
<!-- res/layout/fullscreen_dialog.xml -->
<LinearLayout
    xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:orientation="vertical"
    android:padding="16dp">
    <TextView
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:text="@string/fullscreen_title"
        android:textAppearance="?attr/textAppearanceHeadlineSmall"/>
    <!-- Add custom content, e.g., form fields -->
    <Button
        android:id="@+id/close_button"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:layout_gravity="end"
        android:text="@string/close"/>
</LinearLayout>
      
      
    

Anatomy and Key Properties 📏

A full-screen dialog fills the screen with custom content. 📺

• Container: Full-screen, custom layout.
• Content: Custom views, e.g., forms. 📋
• Scrim: Optional, dims background. 🌑

Attributes (Basic Dialog) 📋

Element	Attribute	Related method(s)	Default value
Container	app:backgroundTint	N/A	?attr/colorSurfaceContainerHigh
	app:shapeAppearance	N/A	?attr/shapeAppearanceCornerExtraLarge
Title	N/A	setTitle, setCustomTitle	null
Content	N/A	setMessage, setView	null
Buttons	N/A	setPositiveButton, setNegativeButton, setNeutralButton	null
Scrim	android:backgroundDimAmount	N/A	32%

Styles 🎨

• Default style: MaterialAlertDialog.Material3
• Default theme overlay: ThemeOverlay.Material3.MaterialAlertDialog
• Centered theme overlay: ThemeOverlay.Material3.MaterialAlertDialog.Centered
• Default style theme attribute: ?attr/alertDialogStyle

See the full list of styles and attrs. 🔗

Theming Dialogs 🖌️

Material Theming customizes dialog colors, typography, and shapes. 🎨

Theming Example 💻

Theming example for dialogs:

      
<style name="Theme.App" parent="Theme.Material3.*">
    <item name="colorPrimary">@color/shrine_pink_100</item>
    <item name="colorSurface">@color/shrine_pink_light</item>
</style>
      
      
    

Specific theme overlay for dialogs without affecting other components:

      
<style name="Theme.App" parent="Theme.Material3.*">
    <item name="materialAlertDialogTheme">@style/ThemeOverlay.App.MaterialAlertDialog</item>
</style>

<style name="ThemeOverlay.App.MaterialAlertDialog" parent="ThemeOverlay.Material3.MaterialAlertDialog">
    <item name="colorPrimary">@color/shrine_pink_100</item>
    <item name="colorSurface">@color/shrine_pink_light</item>
</style>
      
      
    

FAQ ❓

What are Material 3 Dialogs? 🤔

Modal windows for critical information or user decisions. ✅

---

How many dialog variants are there? 🔢

Two variants: Basic and Full-screen. 🔔

---

When to use a Full-screen Dialog? 🖋️

Use for complex tasks, like forms or multi-step processes. 📺

---

How to make dialogs accessible? ♿

Set contentDescription on icons; ensure focusable elements for TalkBack. 🗣️

---

Can I customize dialog appearance? 🎨

Yes, theme colors, typography, and shapes via res/values/styles.xml. 🖌️

---

How to add the Material 3 library? 📦

Include the Material Components for Android library. See the Get Started guide. 🛠️

---

Are there updates for 2025? 🗓️

This guide reflects 2025 Material 3 standards for dialogs. 🚀