You can download the latest sample APK from this repo here: https://github.com/afollestad/material-dialogs/blob/master/sample/sample.apk
It's also on Google Play:
Having the sample project installed is a good way to be notified of new releases.
Easily reference the library in your Android projects using this dependency in your module's build.gradle file:
dependencies {
compile 'com.afollestad:material-dialogs:0.6.4.7'
} 
See the project's Releases page for a list of versions with their changelogs.
First of all, note that MaterialDialog extends DialogBase, which extends AlertDialog. While
a very small number of the stock methods are purposely deprecated and don't work, you have access
to methods such as dismiss(), setTitle(), setIcon(), etc. Alternatives are discussed below.
Here's a basic example that mimics the dialog you see on Google's Material design guidelines
(here: http://www.google.com/design/spec/components/dialogs.html#dialogs-usage). Note that you can
always substitute literal strings and string resources for methods that take strings, the same goes
for color resources (e.g. titleColor and titleColorRes).
new MaterialDialog.Builder(this)
.title(R.string.title)
.content(R.string.content)
.positiveText(R.string.agree)
.negativeText(R.string.disagree)
.show();On Lollipop (API 21) or if you use AppCompat, the Material dialog will automatically match the positiveColor
(which is used on the positive action button) to the colorAccent attribute of your styles.xml theme.
If the content is long enough, it will become scrollable and a divider will be displayed above the action buttons.
If you're migrating old dialogs you could use AlertDialogWrapper. You need change imports and replace AlertDialog.Builder with AlertDialogWrapper.Builder:
new AlertDialogWrapper.Builder(this)
.setTitle(R.string.title)
.setMessage(R.string.message)
.setNegativeButton(R.string.OK, new DialogInterface.OnClickListener() {
@Override
public void onClick(DialogInterface dialog, int which) {
dialog.dismiss();
}
}).show();But it's highly recommended to use original MaterialDialog API for new usages.
MaterialDialog supports the display of an icon just like the stock AlertDialog; it will go to the left of the title.
new MaterialDialog.Builder(this)
.title(R.string.title)
.content(R.string.content)
.positiveText(R.string.agree)
.icon(R.drawable.icon)
.show();You can limit the maximum size of the icon using the limitIconToDefaultSize(), maxIconSize(int size),
or maxIconSizeRes(int sizeRes) Builder methods.
If you have multiple action buttons that together are too wide to fit on one line, the dialog will stack the buttons to be vertically orientated.
new MaterialDialog.Builder(this)
.title(R.string.title)
.content(R.string.content)
.positiveText(R.string.longer_positive)
.negativeText(R.string.negative)
.show();You can also force the dialog to stack its buttons with the forceStacking() method of the Builder.
You can specify neutral text in addition to the positive and negative text. It will show the neutral action on the far left.
new MaterialDialog.Builder(this)
.title(R.string.title)
.content(R.string.content)
.positiveText(R.string.agree)
.negativeText(R.string.disagree)
.neutralText(R.string.more_info)
.show();To know when the user selects an action button, you set a callback. To do this, use the ButtonCallback
class and override its onPositive(), onNegative(), or onNeutral() methods as needed. The advantage
to this is that you can override button functionality À la carte, so no need to stub empty methods.
new MaterialDialog.Builder(this)
.callback(new MaterialDialog.ButtonCallback() {
@Override
public void onPositive(MaterialDialog dialog) {
}
});
new MaterialDialog.Builder(this)
.callback(new MaterialDialog.ButtonCallback() {
@Override
public void onPositive(MaterialDialog dialog) {
}
@Override
public void onNegative(MaterialDialog dialog) {
}
});
new MaterialDialog.Builder(this)
.callback(new MaterialDialog.ButtonCallback() {
@Override
public void onPositive(MaterialDialog dialog) {
}
@Override
public void onNegative(MaterialDialog dialog) {
}
@Override
public void onNeutral(MaterialDialog dialog) {
}
});If autoDismiss is turned off, then you must manually dismiss the dialog in these callbacks. Auto dismiss is on by default.
Creating a list dialog only requires passing in an array of strings. The callback (itemsCallback) is
also very simple.
new MaterialDialog.Builder(this)
.title(R.string.title)
.items(R.array.items)
.itemsCallback(new MaterialDialog.ListCallback() {
@Override
public void onSelection(MaterialDialog dialog, View view, int which, CharSequence text) {
}
})
.show();If autoDismiss is turned off, then you must manually dismiss the dialog in the callback. Auto dismiss is on by default.
You can pass positiveText() or the other action buttons to the builder to force it to display the action buttons
below your list, however this is only useful in some specific cases.
Single choice list dialogs are almost identical to regular list dialogs. The only difference is that
you use itemsCallbackSingleChoice to set a callback rather than itemsCallback. That signals the dialog to
display radio buttons next to list items.
new MaterialDialog.Builder(this)
.title(R.string.title)
.items(R.array.items)
.itemsCallbackSingleChoice(-1, new MaterialDialog.ListCallback() {
@Override
public void onSelection(MaterialDialog dialog, View view, int which, CharSequence text) {
}
})
.positiveText(R.string.choose)
.show();If you want to preselect an item, pass an index 0 or greater in place of -1 in itemsCallbackSingleChoice().
Later, you can update the selected index using setSelectedIndex(int) on the MaterialDialog instance,
if you're not using a custom adapter.
If you do not set a positive action button using positiveText(), the dialog will automatically call
the single choice callback when user presses the positive action button. The dialog will also dismiss itself,
unless auto dismiss is turned off.
If you make a call to alwaysCallSingleChoiceCallback(), the single choice callback will be called
every time the user selects an item.
Multiple choice list dialogs are almost identical to regular list dialogs. The only difference is that
you use itemsCallbackMultiChoice to set a callback rather than itemsCallback. That signals the dialog to
display check boxes next to list items, and the callback can return multiple selections.
new MaterialDialog.Builder(this)
.title(R.string.title)
.items(R.array.items)
.itemsCallbackMultiChoice(null, new MaterialDialog.ListCallbackMulti() {
@Override
public void onSelection(MaterialDialog dialog, Integer[] which, CharSequence[] text) {
}
})
.positiveText(R.string.choose)
.show();If you want to preselect any items, pass an array of indices (resource or literal) in place of null
in itemsCallbackMultiChoice(). Later, you can update the selected indices using setSelectedIndices(Integer[])
on the MaterialDialog instance, if you're not using a custom adapter.
If you do not set a positive action button using positiveText(), the dialog will automatically call
the multi choice callback when user presses the positive action button. The dialog will also dismiss itself,
unless auto dismiss is turned off.
If you make a call to alwaysCallMultiChoiceCallback(), the multi choice callback will be called
every time the user selects an item.
Like Android's native dialogs, you can also pass in your own adapter via .adapter() to customize
exactly how you want your list to work.
new MaterialDialog.Builder(this)
.title(R.string.socialNetworks)
.adapter(new ButtonItemAdapter(this, R.array.socialNetworks),
new MaterialDialog.ListCallback() {
@Override
public void onSelection(MaterialDialog dialog, View itemView, int which, CharSequence text) {
Toast.makeText(MainActivity.this, "Clicked item " + which, Toast.LENGTH_SHORT).show();
}
})
.show();If you need access to the ListView, you can use the MaterialDialog instance:
MaterialDialog dialog = new MaterialDialog.Builder(this)
...
.build();
ListView list = dialog.getListView();
// Do something with it
dialog.show();Note that you don't need to be using a custom adapter in order to access the ListView, it's there for single/multi choice dialogs, regular list dialogs, etc.
Custom views are very easy to implement.
boolean wrapInScrollView = true;
new MaterialDialog.Builder(this)
.title(R.string.title)
.customView(R.layout.custom_view, wrapInScrollView)
.positiveText(R.string.positive)
.build()
.show();If wrapInScrollView is true, then the library will place your custom view inside of a ScrollView for you.
This allows users to scroll your custom view if necessary (small screens, long content, etc.). However, there are cases
when you don't want that behavior. This mostly consists of cases when you'd have a ScrollView in your custom layout,
including ListViews, RecyclerViews, WebViews, GridViews, etc. The sample project contains examples of using both true
and false for this parameter.
Your custom view will automatically have padding put around it when wrapInScrollView is true. Otherwise
you're responsible for using padding values that look good with your content.
By default, Material Dialogs will use the Roboto Medium font for the dialog title and action buttons,
and Roboto Regular for content, list items, etc. This is done so using the font assets included in this library,
so these fonts will be used even on Samsung devices that by default use weird handwriting typefaces.
If you want this default behavior to be avoided, you can make a call to disableDefaultFonts() when
using the Builder. This will result in the library not applying Roboto and Roboto Medium fonts,
and everything will use the regular system font.
If you want to explicitly use custom fonts, you can make a call to typeface(String, String) when
using the Builder. This will pull fonts from TTF files in your project's assets folder. For example,
if you had Roboto.ttf and Roboto-Light.ttf in /src/main/assets/fonts, you would call typeface("Roboto", "Roboto-Light").
Note that no extension is used in the name. This method will also handle recycling Typefaces via the TypefaceHelper which
you can use in your own project to avoid duplicate allocations.
Before Lollipop, theming AlertDialogs was basically impossible without using reflection and custom drawables. Since KitKat, Android became more color neutral but AlertDialogs continued to use Holo Blue for the title and title divider. Lollipop has improved even more, with no colors in the dialog by default other than the action buttons. This library makes theming even easier. Here's a basic example:
new MaterialDialog.Builder(this)
.title(R.string.title)
.content(R.string.content)
.positiveText(R.string.positive)
.neutralText(R.string.neutral)
.negativeText(R.string.negative)
.positiveColorRes(R.color.material_red_500)
.neutralColorRes(R.color.material_red_500)
.negativeColorRes(R.color.material_red_500)
.titleGravity(GravityEnum.CENTER_HORIZONTAL)
.contentGravity(GravityEnum.CENTER_HORIZONTAL)
.btnStackedGravity(GravityEnum.START)
.titleColorRes(R.color.material_red_500)
.contentColorRes(Color.WHITE)
.dividerColorRes(R.color.material_pink_500)
.backgroundColorRes(R.color.material_blue_grey_800)
.btnSelectorStacked(R.drawable.custom_btn_selector_stacked)
.btnSelector(R.drawable.custom_btn_selector)
.btnSelector(R.drawable.custom_btn_selector_primary, DialogAction.POSITIVE)
.listSelector(R.drawable.custom_list_and_stackedbtn_selector)
.theme(Theme.DARK)
.show();To see more colors that fit the Material design palette, see this page: http://www.google.com/design/spec/style/color.html#color-color-palette
An important note related to using custom action button selectors: make sure your selector drawable references inset drawables like the default ones do, this is important for correct action button padding.
By default, the dialog inherits and extracts theme colors from other attributes and theme colors of the app or operating system. This behavior can be overridden in your Activity themes:
<style name="AppTheme" parent="Theme.AppCompat.Light.DarkActionBar">
<!--
All dialogs will default to Theme.DARK with this set to true.
-->
<item name="md_dark_theme">true</item>
<!--
This overrides the default dark or light dialog background color.
Note that if you use a dark color here, you should set md_dark_theme to
true so text and selectors look visible
-->
<item name="md_background_color">#37474F</item>
<!--
Applies an icon next to the title in all dialogs.
-->
<item name="md_icon">@drawable/ic_launcher</item>
<!--
Limit icon to a max size.
-->
<attr name="md_icon_max_size" format="dimension" />
<!--
Limit the icon to a default max size (32dp).
-->
<attr name="md_icon_limit_icon_to_default_size" format="boolean" />
<!--
By default, the title text color is derived from the
?android:textColorPrimary system attribute.
-->
<item name="md_title_color">#E91E63</item>
<!--
By default, the content text color is derived from the
?android:textColorSecondary system attribute.
-->
<item name="md_content_color">#9C27B0</item>
<!--
By default, the positive action text color is derived
from the colorAccent attribute of AppCompat or android:colorAccent
attribute of the Material theme.
-->
<item name="md_positive_color">#673AB7</item>
<!--
By default, the positive action text color is derived
from the colorAccent attribute of AppCompat or android:colorAccent
attribute of the Material theme.
-->
<item name="md_neutral_color">#673AB7</item>
<!--
By default, the positive action text color is derived
from the colorAccent attribute of AppCompat or android:colorAccent
attribute of the Material theme.
-->
<item name="md_negative_color">#673AB7</item>
<!--
By default, the list item text color is black for the light
theme and white for the dark theme.
-->
<item name="md_item_color">#9C27B0</item>
<!--
This overrides the color used for the top and bottom dividers used when
content is scrollable
-->
<item name="md_divider_color">#E91E63</item>
<!--
This overrides the selector used on list items.
-->
<item name="md_list_selector">@drawable/selector</item>
<!--
This overrides the selector used on stacked action buttons.
-->
<item name="md_btn_stacked_selector">@drawable/selector</item>
<!--
This overrides the background selector used on the positive action button.
-->
<item name="md_btn_positive_selector">@drawable/selector</item>
<!--
This overrides the background selector used on the neutral action button.
-->
<item name="md_btn_neutral_selector">@drawable/selector</item>
<!--
This overrides the background selector used on the negative action button.
-->
<item name="md_btn_negative_selector">@drawable/selector</item>
</style>The action button color is also derived from the android:colorAccent attribute of the Material theme,
or colorAccent attribute of the AppCompat Material theme as seen in the sample project. Manually setting
the color will override that behavior.
You can directly setup show/cancel/dismiss listeners from the Builder rather than on the resulting
MaterialDialog instance:
new MaterialDialog.Builder(this)
.title("Use Google's Location Services?")
.content("Let Google help apps determine location. This means sending anonymous location data to Google, even when no apps are running.")
.positiveText("Agree")
.showListener(new DialogInterface.OnShowListener() {
@Override
public void onShow(DialogInterface dialog) {
}
})
.cancelListener(new DialogInterface.OnCancelListener() {
@Override
public void onCancel(DialogInterface dialog) {
}
})
.dismissListener(new DialogInterface.OnDismissListener() {
@Override
public void onDismiss(DialogInterface dialog) {
}
})
.show();This library allows you to display progress dialogs with Material design that even use your app's accent color to color the progress bars (if you use AppCompat to theme your app, or the Material theme on Lollipop).
This will display the classic progress dialog with a spinning circle, see the sample project to see it in action:
new MaterialDialog.Builder(this)
.title(R.string.progress_dialog)
.content(R.string.please_wait)
.progress(true, 0)
.show();If a dialog is not indeterminate, it displays a horizontal progress bar that increases up until a max value. The comments in the code explain what this does.
// Create and show a non-indeterminate dialog with a max value of 150
// If the showMinMax parameter is true, a min/max ratio will be shown to the left of the seek bar.
boolean showMinMax = true;
MaterialDialog dialog = new MaterialDialog.Builder(this)
.title(R.string.progress_dialog)
.content(R.string.please_wait)
.progress(false, 150, showMinMax)
.show();
// Loop until the dialog's progress value reaches the max (150)
while (dialog.getCurrentProgress() != dialog.getMaxProgress()) {
// If the progress dialog is cancelled (the user closes it before it's done), break the loop
if (dialog.isCancelled()) break;
// Wait 50 milliseconds to simulate doing work that requires progress
try {
Thread.sleep(50);
} catch (InterruptedException e) {
break;
}
// Increment the dialog's progress by 1 after sleeping for 50ms
dialog.incrementProgress(1);
}
// When the loop exits, set the dialog content to a string that equals "Done"
dialog.setContent(getString(R.string.done));See the sample project for this dialog in action, with the addition of threading.
Android's EditTextPreference, ListPreference, and MultiSelectListPreference allow you to associate a preference activity's settings
with user input that's received through typing or selection. Material Dialogs includes MaterialEditTextPreference,
MaterialListPreference, and MaterialMultiSelectListPreference classes that can be used in your preferences XML to automatically use Material-themed
dialogs. See the sample project for details.
If you need to access a View in the custom view set to a MaterialDialog, you can use getCustomView() of
MaterialDialog. This is especially useful if you pass a layout resource to the Builder.
MaterialDialog dialog = //... initialization via the builder ...
View view = dialog.getCustomView();If you want to get a reference to the title frame (which contains the icon and title, e.g. to change visibility):
MaterialDialog dialog = //... initialization via the builder ...
TextView title = dialog.getTitleFrame();If you want to get a reference to one of the dialog action buttons (e.g. to enable or disable buttons):
MaterialDialog dialog = //... initialization via the builder ...
View negative = dialog.getActionButton(DialogAction.NEGATIVE);
View neutral = dialog.getActionButton(DialogAction.NEUTRAL);
View positive = dialog.getActionButton(DialogAction.POSITIVE);If you want to update the title of a dialog action button (you can pass a string resource ID in place of the literal string, too):
MaterialDialog dialog = //... initialization via the builder ...
dialog.setActionButton(DialogAction.NEGATIVE, "New Title");If you don't want the dialog to automatically be dismissed when an action button is pressed or when the user selects a list item:
MaterialDialog dialog new MaterialDialog.Builder(this)
// ... other initialization
.autoDismiss(false)
.show();