A [`DialogFragment`](https://developer.android.com/reference/androidx/fragment/app/DialogFragment) is a
special fragment subclass that is designed for creating and hosting
[dialogs](https://developer.android.com/guide/topics/ui/dialogs). Although you don't need to
host your dialog within a fragment, doing so lets the
[`FragmentManager`](https://developer.android.com/guide/fragments/fragmentmanager) manage the state
of the dialog and automatically restore the dialog when a configuration
change occurs.
| **Note:** This guide assumes familiarity with creating dialogs. For more information, see the [guide to dialogs](https://developer.android.com/guide/topics/ui/dialogs).

## Create a DialogFragment

To create a `DialogFragment`, create a class that extends
[`DialogFragment`](https://developer.android.com/reference/androidx/fragment/app/DialogFragment) and
override
[`onCreateDialog()`](https://developer.android.com/reference/androidx/fragment/app/DialogFragment#onCreateDialog(android.os.Bundle)),
as shown in the following example.  

### Kotlin

```kotlin
class PurchaseConfirmationDialogFragment : DialogFragment() {
    override fun onCreateDialog(savedInstanceState: Bundle?): Dialog =
            AlertDialog.Builder(requireContext())
                .setMessage(getString(R.string.order_confirmation))
                .setPositiveButton(getString(R.string.ok)) { _,_ -> }
                .create()

    companion object {
        const val TAG = "PurchaseConfirmationDialog"
    }
}
```

### Java

```java
public class PurchaseConfirmationDialogFragment extends DialogFragment {
   @NonNull
   @Override
   public Dialog onCreateDialog(@Nullable Bundle savedInstanceState) {
       return new AlertDialog.Builder(requireContext())
               .setMessage(getString(R.string.order_confirmation))
               .setPositiveButton(getString(R.string.ok), (dialog, which) -> {} )
               .create();
   }

   public static String TAG = "PurchaseConfirmationDialog";
}
```

Similar to how
[`onCreateView()`](https://developer.android.com/reference/androidx/fragment/app/Fragment#onCreateView(android.view.LayoutInflater,%20android.view.ViewGroup,%20android.os.Bundle))
creates a root `View` in an ordinary fragment, `onCreateDialog()`
creates a [`Dialog`](https://developer.android.com/reference/android/app/Dialog) to display
as part of the `DialogFragment`. The `DialogFragment` handles displaying
the `Dialog` at appropriate states in the fragment's lifecycle.
| **Note:** `DialogFragment` owns the [`Dialog.setOnCancelListener()`](https://developer.android.com/reference/android/app/Dialog#setOnCancelListener(android.content.DialogInterface.OnCancelListener)) and [`Dialog.setOnDismissListener()`](https://developer.android.com/reference/android/app/Dialog#setOnDismissListener(android.content.DialogInterface.OnDismissListener)) callbacks. You must not set them yourself. To find out about these events, override [`onCancel()`](https://developer.android.com/reference/android/content/DialogInterface.OnCancelListener#onCancel(android.content.DialogInterface)) and [`onDismiss()`](https://developer.android.com/reference/android/content/DialogInterface.OnDismissListener#onDismiss(android.content.DialogInterface)).

As with `onCreateView()`, you can return any subclass of `Dialog`
from `onCreateDialog()` and aren't limited to using
[`AlertDialog`](https://developer.android.com/reference/androidx/appcompat/app/AlertDialog).

## Show the DialogFragment

You don't have to manually create a `FragmentTransaction` to
display your `DialogFragment`. Instead, use the `show()` method to
display your dialog. You can pass a reference to a `FragmentManager`
and a `String` to use as a `FragmentTransaction` tag.

When creating
a `DialogFragment` from within a `Fragment`, use the fragment's
child `FragmentManager` so that the state properly restores
after configuration changes. A non-null tag lets you use
`findFragmentByTag()` to retrieve the `DialogFragment` at a later time.  

### Kotlin

```kotlin
// From another Fragment or Activity where you wish to show this
// PurchaseConfirmationDialogFragment.
PurchaseConfirmationDialogFragment().show(
     childFragmentManager, PurchaseConfirmationDialog.TAG)
```

### Java

```java
// From another Fragment or Activity where you wish to show this
// PurchaseConfirmationDialogFragment.
new PurchaseConfirmationDialogFragment().show(
       getChildFragmentManager(), PurchaseConfirmationDialog.TAG);
```

For more control over the
[`FragmentTransaction`](https://developer.android.com/reference/androidx/fragment/app/FragmentTransaction),
you can use the
[`show()`](https://developer.android.com/reference/androidx/fragment/app/DialogFragment#show(androidx.fragment.app.FragmentManager,%20java.lang.String))
overload that accepts an existing `FragmentTransaction`.
| **Note:** Because the `DialogFragment` automatically restores after configuration changes, consider only calling `show()` based on user actions or when `findFragmentByTag()` returns `null`, indicating that the dialog is not already present.

## DialogFragment lifecycle

A `DialogFragment` follows the standard fragment lifecycle,
with a few additional lifecycle callbacks. The most
common ones are as follows:

- [`onCreateDialog()`](https://developer.android.com/reference/androidx/fragment/app/DialogFragment#onCreateDialog(android.os.Bundle)): override this callback to provide a `Dialog` for the fragment to manage and display.
- [`onDismiss()`](https://developer.android.com/reference/androidx/fragment/app/DialogFragment#onDismiss(android.content.DialogInterface)): override this callback if you need to perform any custom logic when your `Dialog` is dismissed, such as releasing resources or unsubscribing from observable resources.
- [`onCancel()`](https://developer.android.com/reference/androidx/fragment/app/DialogFragment#onCancel(android.content.DialogInterface)): override this callback if you need to perform any custom logic when your `Dialog` is canceled.

`DialogFragment` also contains methods to dismiss or set the cancelability
of your `DialogFragment`:

- [`dismiss()`](https://developer.android.com/reference/androidx/fragment/app/DialogFragment#dismiss()): dismiss the fragment and its dialog. If the fragment was added to the back stack, all back stack state up to and including this entry are popped. Otherwise, a new transaction is committed to remove the fragment.
- [`setCancelable()`](https://developer.android.com/reference/androidx/fragment/app/DialogFragment#setCancelable(boolean)): control whether the shown `Dialog` is cancelable. Use this method instead of directly calling [`Dialog.setCancelable(boolean)`](https://developer.android.com/reference/android/app/Dialog#setCancelable(boolean)).

You don't override
[`onCreateView()`](https://developer.android.com/reference/androidx/fragment/app/Fragment#oncreateview)
or
[`onViewCreated()`](https://developer.android.com/reference/androidx/fragment/app/Fragment#onViewCreated(android.view.View,%20android.os.Bundle))
when using a `DialogFragment` with a `Dialog`. Dialogs aren't only
views---they have their own window. As such, it's not enough to override
`onCreateView()`. Moreover, `onViewCreated()` is never called on a
custom `DialogFragment` unless you've overridden `onCreateView()` and
provided a non-null view.
| **Note:** When subscribing to lifecycle-aware components such as `LiveData`, never use [`viewLifecycleOwner`](https://developer.android.com/reference/androidx/fragment/app/Fragment#getviewlifecycleowner) as the [LifecycleOwner](https://developer.android.com/reference/androidx/lifecycle/LifecycleOwner) in a `DialogFragment` that uses `Dialog` objects. Instead, use the `DialogFragment` itself, or, if you're using [Jetpack Navigation](https://developer.android.com/guide/navigation), use the [`NavBackStackEntry`](https://developer.android.com/reference/androidx/navigation/NavBackStackEntry).

## Use custom views

You can create a `DialogFragment` and display a dialog by overriding
[`onCreateView()`](https://developer.android.com/reference/androidx/fragment/app/Fragment#onCreateView(android.view.LayoutInflater,%20android.view.ViewGroup,%20android.os.Bundle)).
You can either give it a `layoutId`, as with a typical fragment, or use the
[`DialogFragment` constructor](https://developer.android.com/reference/androidx/fragment/app/DialogFragment#DialogFragment(int)).

The `View` returned by `onCreateView()`
is automatically added to the dialog. In most cases, this means that you
don't need to override
[`onCreateDialog()`](https://developer.android.com/reference/androidx/fragment/app/DialogFragment#onCreateDialog(android.os.Bundle)),
as the default empty dialog is populated with your view.

Certain subclasses of `DialogFragment`, such as
[`BottomSheetDialogFragment`](https://developer.android.com/reference/com/google/android/material/bottomsheet/BottomSheetDialogFragment),
embed your view in a dialog that is styled as a bottom sheet.