Hands-on with Material Components for Android: Buttons

Part 4 of a series covering practical usage of Material Components for Android

Nick Rout
Nick Rout
Apr 12 · 7 min read

This post will be covering the features and API of Button components. To find out how to handle initial setup of Material Components for Android (including the Gradle dependency and creating an app theme), please see my original post:

Buttons are arguably the most widely-used components in any app. This is largely due to their versatility, allowing users to perform actions and make choices that ultimately guide the flow of an experience. A single line of contained text and/or an icon indicate the action a button can perform.

Material Buttons are slightly different to traditional Android buttons in that they include additional insets (4dp on the left/right), more letter-spacing, different default colors and more in order to improve legibility and affordance amongst other components.

Traditional Android button

From a design perspective, there are three main types of buttons which are intended to offer hierarchical levels of emphasis:

  • Text button (low emphasis): No container. Best used for less important actions, especially when other main content needs to be emphasised.
Text button
  • Outlined button (medium emphasis): Stroked container. Best used for important (but not primary) actions and offer a “lighter” visual feel.
Outlined button
  • Contained button (high emphasis): Filled container. Best used for primary actions that should draw the users attention. These can either be raised or unelevated.
Unelevated (left) and raised (right) contained buttons

In addition to this, buttons can be grouped together into a fourth type: Toggle button. This allows related button actions to be horizontally arranged in a common container. The buttons themselves can be selected/deselected to indicate an active/inactive choice.

Toggle button

Basic usage 🏁

A MaterialButton can be included in your layout like so:




Choosing a style 🤔

As discussed in the intro section above, a variety of button types exist. These types map to styles that you can apply to a MaterialButton. There also exists a variety of sub-styles for specific use cases, such as to adjust padding for an icon. The full list of styles and their attributes can be found on GitHub. These style variants inherit from Widget.MaterialComponents.Button, each with an optional style suffix:

  • Text button: *.TextButton (main), *.TextButton.Icon, *.TextButton.Snackbar, *.TextButton.Dialog, *.TextButton.Dialog.Icon, *.TextButton.Dialog.Flush
  • Outlined button: *.OutlinedButton (main), *.OutlinedButton.Icon
  • Contained button (unelevated): *.UnelevatedButton (main), *.UnelevatedButton.Icon
  • Contained button (raised): No suffix (default, main), *.Icon

Adding an icon 🔷

An icon can be added to a button. It is displayed at the start, before the text label. In order to get the correct icon padding, it is recommended that you use a *.Icon style variant (shown above in the “Choosing a style” section).

Button with icon

The icon can be added in XML:


Alternatively, it can be done programmatically:

// Using icon resource ID
// Using icon Drawable
val showDrawable = AppCompatResources.getDrawable(context, R.drawable.ic_show_black_18dp)
textButton.icon = showDrawable

A few additional attributes exist for adjusting the icon size and position:

  • iconSize: The width/height of the icon. The default value is the supplied Drawable’s intrinsic width.
  • iconGravity: The gravity of the icon. This can be set to start (ICON_GRAVITY_START, default, at start of button), end (ICON_GRAVITY_END, at end of button), textStart (ICON_GRAVITY_TEXT_START, at start of centered text label) or textEnd (ICON_GRAVITY_TEXT_END, at end of centered text label).
  • iconPadding: The spacing between the icon and the text label. Typically you would not want to change this. The default value is 4dp for text buttons and 8dp for all other types.

Attributes related to icon tinting are discussed in the “Theming” section below.

Grouping Buttons to create a Toggle Button 👨‍👩‍👧‍👦

In order to create a toggle button, we need to add MaterialButtons as child Views to a MaterialButtonToggleGroup (a custom ViewGroup).

Note: MaterialButtonToggleGroup was added in the 1.1.0-alpha05 release of Material Components for Android.


This can be done in XML:





Alternatively, it can be done programmatically:

toggleGroup.addView(button1, 0, layoutParams)
toggleGroup.addView(button2, 1, layoutParams)
toggleGroup.addView(button3, 2, layoutParams)

The MaterialButtonToggleGroup handles layout and adjusting of only the relevant shape corners in the row of MaterialButtons. The appearance of the MaterialButtons is determined by whichever style they each use. It is advised to use a consistent style for all children and also recommended to use the outlined button type.

Adjusting selected behavior

When added to a MaterialButtonToggleGroup, child MaterialButtons automatically become “selectable” (i.e. The android:checkable attribute is set to true).

Thus, there exists a couple of attributes for adjusting how MaterialButtonToggleGroup manages this:

  • singleSelection: Determines whether or not only a single button in the group can be checked at a time. The default value is false, meaning multiple buttons can be checked/unchecked independently.
singleSelection set to true/false
  • checkedButton: The ID of the button that should be checked by default. The default value View.NO_ID.

Listening for selection state

We are able to query for and adjust the current checked button(s) in a variety of ways:

val checkedId = toggleGroup.checkedButtonId // Will return View.NO_ID if singleSelection = false
val checkedIds = toggleGroup.checkedButtonIds // Potentially an empty list
toggleGroup.check(R.id.button1) // Checks a specific button
toggleGroup.uncheck(R.id.button1) // Unchecks a specific button
toggleGroup.clearChecked() // Unchecks all buttons

We are also able to listen for checked changes by adding an OnButtonCheckedListener to a MaterialButtonToggleGroup:

toggleGroup.addOnButtonCheckedListener { group, checkedId, isChecked ->
// Do something for checked change

Listeners can also be removed with the MaterialButtonToggleGroup#removeListener and MaterialButtonToggleGroup#clearListeners functions.

Theming 🎨

Buttons can be themed in terms of the three Material Theming subsystems: color, typography and shape. We have already shown which styles to use in the “Choosing a style” section above. When implementing a global custom MaterialButton and MaterialButtonToggleGroup styles, reference them in your app theme with the materialButtonStyle/materialButtonOutlinedStyle and materialButtonToggleGroupStyle attributes respectively.


The color of the MaterialButton background can be customized with the backgroundTint attribute. This requires a ColorStateList, meaning a <selector> for checked/enabled/disabled states is required. It defaults to colorPrimary(enabled)/colorOnSurface(disabled) for contained buttons and transparent(unchecked)/colorPrimary(checked) for all other types, with different opacities per state. There is also a backgroundTintMode attribute to change the tint PorterDuff.Mode, although typically you would want to keep this the same.

The color of the text label can be customized with the android:textColor attribute. This too requires a ColorStateList. It defaults to colorOnPrimary(enabled)/colorOnSurface(disabled) for contained buttons and colorPrimary(enabled or checked)/colorOnSurface(disabled or unchecked) for all other types, with different opacities per state.

The color of the optional icon can be customized with the iconTint attribute. This too requires a ColorStateList and the defaults are the same as those of android:textColor. As before, there is also an iconTintMode attribute.

Lastly, the color of the button touch ripple can be customized with the rippleColor attribute. It too accepts a ColorStateList and defaults to colorOnPrimary for contained buttons and colorPrimary for all other types, with different opacities per state.

Color theming


The button text label will adopt the fontFamily attribute defined in your app theme.

While you would typically want to keep most aspects of the button text appearance as is, the Material Guidelines suggest we can use sentence case over the standard all caps for the text label, if desired. To achieve this, we would create a new style:

<style name="ButtonTextAppearance" parent="TextAppearance.MaterialComponents.Button">
<item name="android:textAllCaps">false</item>

We could apply this directly to a button or in an individual button style by referencing it with the android:textAppearance attribute. Alternatively, it can be applied globally by referencing it in your app theme with the textAppearanceButton attribute.

Type theming


The shape of a button background can be customized with the shapeAppearance attribute. This defaults to shapeAppearanceSmallComponent.

While not strictly shape theming, it is worth mentioning that the width of an outlined button stroke can be adjusted with the strokeWidth attribute. This defaults to 1dp.

Shape theming

More resources 📚

I hope this post has provided some insight into Material Buttons and how they can be used in your Android app(s). If you have any questions, thoughts or suggestions then I’d love to hear from you!

Find me on Twitter @ricknout

Over Engineering

Over is a mobile app for creativity that allows you to build beautiful custom designs

Thanks to Rebecca Franks

Nick Rout

Written by

Nick Rout

Android Engineer at Over | Google Developer Expert for Android | GDG Cape Town Organizer | 🌚

Over Engineering

Over is a mobile app for creativity that allows you to build beautiful custom designs

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade