Buttons

Buttons allow users to take actions, and make choices, with a single tap.

Contents

Using buttons
Text button
Outlined button
Contained button
Toggle button
Theming

Using buttons

Before you can use Material buttons, you need to add a dependency to the Material Components for Android library. For more information, go to the Getting started page.

Note: <Button> is auto-inflated as <com.google.android.material.button.MaterialButton> via MaterialComponentsViewInflater when using a non-Bridge Theme.MaterialComponents.* theme.

Making buttons accessible

Buttons support content labeling for accessibility and are readable by most screen readers, such as TalkBack. Text rendered in buttons is automatically provided to accessibility services. Additional content labels are usually unnecessary.

For more information on content labels, go to the Android accessibility help guide.

Types

There are four types of buttons: 1. Text button, 2. Outlined button, 3. Contained button, 4. Toggle button

Text button

Text buttons are typically used for less-pronounced actions, including those located in dialogs and cards. In cards, text buttons help maintain an emphasis on card content.

Text button examples

API and source code:

MaterialButton
- Class description
- Class source

The following example shows a text button with a text label.

In the layout:

<Button
    android:id="@+id/textButton"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:text="Text button"
    style="@style/Widget.MaterialComponents.Button.TextButton"
/>

In code:

textButton.setOnClickListener {
    // Respond to button press
}

Adding an icon to a text button

The following example shows a text button with an icon.

In the layout:

<Button
    ...
    app:icon="@drawable/ic_add_24dp"
    style="@style/Widget.MaterialComponents.Button.TextButton.Icon"
/>

Anatomy and key properties

A text button has a text label, a transparent container and an optional icon.

Text label
Icon

Text label attributes

Element	Attribute	Related method(s)	Default value
Text label	`android:text`	`setText` `getText`	`null`
Color	`android:textColor`	`setTextColor` `getTextColor`	`?attr/colorPrimary` (see all states)
Typography	`android:textAppearance`	`setTextAppearance`	`?attr/textAppearanceButton`

Container attributes

Element	Attribute	Related method(s)	Default value
Color	`app:backgroundTint`	`setBackgroundColor` `setBackgroundTintList` `getBackgroundTintList`	`@android:color/transparent` (see all states)
Stroke color	`app:strokeColor`	`setStrokeColor` `setStrokeColorResource` `getStrokeColor`	`null`
Stroke width	`app:strokeWidth`	`setStrokeWidth` `setStrokeWidthResource` `getStrokeWidth`	`0dp`
Shape	`app:shapeAppearance`	`setShapeAppearanceModel` `getShapeAppearanceModel`	`?attr/shapeAppearanceSmallComponent`
Elevation	`app:elevation`	`setElevation` `getElevation`	`0dp`
Ripple color	`app:rippleColor`	`setRippleColor` `setRippleColorResource` `getRippleColor`	`?attr/colorPrimary` at 12% opacity (see all states)

Icon attributes

Element	Attribute	Related method(s)	Default value
Icon	`app:icon`	`setIcon` `setIconResource` `getIcon`	`null`
Color	`app:iconTint`	`setIconTint` `setIconTintResource` `getIconTint`	`?attr/colorPrimary` (see all states)
Size	`app:iconSize`	`setIconSize` `getIconSize`	`wrap_content`
Gravity (position relative to text label)	`app:iconGravity`	`setIconGravity` `getIconGravity`	`start`
Padding (space between icon and text label)	`app:iconPadding`	`setIconPadding` `getIconPadding`	`4dp`

Styles

Element	Style
Default style	`Widget.MaterialComponents.Button.TextButton`
Icon style	`Widget.MaterialComponents.Button.TextButton.Icon`
Full Width Buttons	`Widget.MaterialComponents.Button.TextButton.Dialog.FullWidth`

Default style theme attribute: ?attr/borderlessButtonStyle

See the full list of styles and attrs.

Outlined button

Outlined buttons are medium-emphasis buttons. They contain actions that are important, but aren’t the primary action in an app.

Outlined button examples

API and source code:

MaterialButton
- Class description
- Class source

The following example shows an outlined button with a text label and stroked container.

In the layout:

<Button
    android:id="@+id/outlinedButton"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:text="Outlined button"
    style="?attr/materialButtonOutlinedStyle"
/>

In code:

outlinedButton.setOnClickListener {
    // Respond to button press
}

Adding an icon to an outlined button

The following example shows an outlined button with an icon.

In the layout:

<Button
    ...
    app:icon="@drawable/ic_add_24dp"
    style="@style/Widget.MaterialComponents.Button.OutlinedButton.Icon"
/>

Anatomy and key properties

An outlined button has a text label, a stroked container and an optional icon.

Text label
Container
Icon

Text label attributes

Element	Attribute	Related method(s)	Default value
Text label	`android:text`	`setText` `getText`	`null`
Color	`android:textColor`	`setTextColor` `getTextColor`	`?attr/colorPrimary` (see all states)
Typography	`android:textAppearance`	`setTextAppearance`	`?attr/textAppearanceButton`

Container attributes

Element	Attribute	Related method(s)	Default value
Color	`app:backgroundTint`	`setBackgroundColor` `setBackgroundTintList` `getBackgroundTintList`	`@android:color/transparent` (see all states)
Stroke color	`app:strokeColor`	`setStrokeColor` `setStrokeColorResource` `getStrokeColor`	`?attr/colorOnSurface` at 12% opacity (see all states)
Stroke width	`app:strokeWidth`	`setStrokeWidth` `setStrokeWidthResource` `getStrokeWidth`	`1dp`
Shape	`app:shapeAppearance`	`setShapeAppearanceModel` `getShapeAppearanceModel`	`?attr/shapeAppearanceSmallComponent`
Elevation	`app:elevation`	`setElevation` `getElevation`	`0dp`
Ripple color	`app:rippleColor`	`setRippleColor` `setRippleColorResource` `getRippleColor`	`?attr/colorPrimary` at 12% opacity (see all states)

Icon attributes

Element	Attribute	Related method(s)	Default value
Icon	`app:icon`	`setIcon` `setIconResource` `getIcon`	`null`
Color	`app:iconTint`	`setIconTint` `setIconTintResource` `getIconTint`	`?attr/colorPrimary` (see all states)
Size	`app:iconSize`	`setIconSize` `getIconSize`	`wrap_content`
Gravity (position relative to text label)	`app:iconGravity`	`setIconGravity` `getIconGravity`	`start`
Padding (space between icon and text label)	`app:iconPadding`	`setIconPadding` `getIconPadding`	`4dp`

Styles

Element	Style
Default style	`Widget.MaterialComponents.Button.OutlinedButton`
Icon style	`Widget.MaterialComponents.Button.OutlinedButton.Icon`

Default style theme attribute: ?attr/materialButtonOutlinedStyle

See the full list of styles and attrs.

Contained button

Contained buttons are high-emphasis, distinguished by their use of elevation and fill. They contain actions that are primary to your app.

Note The contained button is the default style if the style is not set.

Contained button examples

API and source code:

MaterialButton
- Class description
- Class source

The following example shows a contained button with a text label and a filled container.

In the layout:

<Button
    android:id="@+id/containedButton"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:text="Contained button"
/>

Note: Since this is the default type, you don't need to specify a style tag as long as you are using a Material Components Theme. If not, set the style to @style/Widget.MaterialComponents.Button.

In code:

containedButton.setOnClickListener {
    // Respond to button press
}

Adding an icon to a contained button

The following example shows a contained button with an icon.

In the layout:

<Button
    ...
    app:icon="@drawable/ic_add_24dp"
    style="@style/Widget.MaterialComponents.Button.Icon"
/>

Anatomy and key properties

A contained button has a text label, a filled container and an optional icon.

Text label
Container
Icon

Text label attributes

Element	Attribute	Related method(s)	Default value
Text label	`android:text`	`setText` `getText`	`null`
Color	`android:textColor`	`setTextColor` `getTextColor`	`?attr/colorOnPrimary` (see all states)
Typography	`android:textAppearance`	`setTextAppearance`	`?attr/textAppearanceButton`

Container attributes

Element	Attribute	Related method(s)	Default value
Color	`app:backgroundTint`	`setBackgroundColor` `setBackgroundTintList` `getBackgroundTintList`	`?attr/colorPrimary` (see all states)
Stroke color	`app:strokeColor`	`setStrokeColor` `setStrokeColorResource` `getStrokeColor`	`null`
Stroke width	`app:strokeWidth`	`setStrokeWidth` `setStrokeWidthResource` `getStrokeWidth`	`0dp`
Shape	`app:shapeAppearance`	`setShapeAppearanceModel` `getShapeAppearanceModel`	`?attr/shapeAppearanceSmallComponent`
Elevation	`app:elevation`	`setElevation` `getElevation`	`2dp`
Ripple color	`app:rippleColor`	`setRippleColor` `setRippleColorResource` `getRippleColor`	`?attr/colorOnPrimary` at 24% opacity (see all states)

Icon attributes

Element	Attribute	Related method(s)	Default value
Icon	`app:icon`	`setIcon` `setIconResource` `getIcon`	`null`
Color	`app:iconTint`	`setIconTint` `setIconTintResource` `getIconTint`	`?attr/colorOnPrimary` (see all states)
Size	`app:iconSize`	`setIconSize` `getIconSize`	`wrap_content`
Gravity (position relative to text label)	`app:iconGravity`	`setIconGravity` `getIconGravity`	`start`
Padding (space between icon and text label)	`app:iconPadding`	`setIconPadding` `getIconPadding`	`4dp`

Styles

Element	Style
Default style	`Widget.MaterialComponents.Button`
Icon style	`Widget.MaterialComponents.Button.Icon`
Unelevated style	`Widget.MaterialComponents.Button.UnelevatedButton`
Unelevated icon style	`Widget.MaterialComponents.Button.UnelevatedButton.Icon`

Default style theme attribute: ?attr/materialButtonStyle

See the full list of styles and attrs.

Toggle button

Toggle buttons can be used to select from a group of choices.

There are two types of toggle buttons:

Toggle button
Icon

Toggle button

To emphasize groups of related toggle buttons, a group should share a common container.

Toggle button examples

API and source code:

MaterialButtonToggleGroup
- Class description
- Class source
MaterialButton
- Class description
- Class source

The following example shows a toggle button with three buttons that have text labels.

In the layout:

<com.google.android.material.button.MaterialButtonToggleGroup
    android:id="@+id/toggleButton"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content">
    <Button
        android:id="@+id/button1"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:text="Button 1"
        style="?attr/materialButtonOutlinedStyle"
    />
    <Button
        android:id="@+id/button2"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:text="Button 2"
        style="?attr/materialButtonOutlinedStyle"
    />
    <Button
        android:id="@+id/button3"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:text="Button 3"
        style="?attr/materialButtonOutlinedStyle"
    />
</com.google.android.material.button.MaterialButtonToggleGroup>

In code:

toggleButton.addOnButtonCheckedListener { toggleButton, checkedId, isChecked ->
    // Respond to button selection
}

Implementing an icon-only toggle button

The following example shows a toggle button with three buttons that have icons.

In res/values/styles.xml:

<style name="Widget.App.Button.OutlinedButton.IconOnly" parent="Widget.MaterialComponents.Button.OutlinedButton">
    <item name="iconPadding">0dp</item>
    <item name="android:insetTop">0dp</item>
    <item name="android:insetBottom">0dp</item>
    <item name="android:paddingLeft">12dp</item>
    <item name="android:paddingRight">12dp</item>
    <item name="android:minWidth">48dp</item>
    <item name="android:minHeight">48dp</item>
</style>

In the layout:

<com.google.android.material.button.MaterialButtonToggleGroup
    ...>
    <Button
        ...
        app:icon="@drawable/ic_favorite_24dp"
        style="@style/Widget.App.Button.OutlinedButton.IconOnly"
    />
    <Button
        ...
        app:icon="@drawable/ic_remove_red_eye_24dp"
        style="@style/Widget.App.Button.OutlinedButton.IconOnly"
    />
    <Button
        ...
        app:icon="@drawable/ic_notifications_24dp"
        style="@style/Widget.App.Button.OutlinedButton.IconOnly"
    />
</com.google.android.material.button.MaterialButtonToggleGroup>

Anatomy and key properties

A toggle button has a shared stroked container, icons and/or text labels.

Container
Icon

Selection attributes

Element	Attribute	Related method(s)	Default value
Single selection	`app:singleSelection`	`setSingleSelection` `isSingleSelection`	`false`
Selection required	`app:selectionRequired`	`setSelectionRequired` `isSelectionRequired`	`false`

Styles

Element	Style
Default style	`Widget.MaterialComponents.MaterialButtonToggleGroup`

Default style theme attribute: ?attr/materialButtonToggleGroupStyle

See the full list of styles and attrs.

Icon

Icons can be used as toggle buttons when they allow selection, or deselection, of a single choice, such as marking an item as a favorite.

Icon example

API and source code:

CheckBox
- Class description

Note The CheckBox API is just one of several inputs that can implement the icon button. See other selection controls for more details.

The following example shows an icon that can be used independently or in items of a RecyclerView.

In the layout:

<CheckBox
    android:id="@+id/icon"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:button="@drawable/sl_favourite_24dp"
    app:buttonTint="@android:color/white"
/>

In res/drawable/sl_favourite_24dp.xml:

<selector>
    <item
        android:drawable="@drawable/ic_favourite_outlined_24dp"
        android:state_checked="false"
    />
    <item
        android:drawable="@drawable/ic_favourite_filled_24dp"
        android:state_checked="true"
    />
    <item android:drawable="@drawable/ic_favourite_outlined_24dp" />
</selector>

In code:

icon.setOnCheckedChangeListener { checkBox, isChecked ->
    // Respond to icon toggle
}

Theming buttons

Buttons support Material Theming and can be customized in terms of color, typography and shape.

Button theming example

API and source code:

MaterialButton
- Class description
- Class source

The following example shows text, outlined and contained button types with Material Theming.

Implementing button theming

Using theme attributes and styles in res/values/styles.xml (themes all buttons and affects other components):

<style name="Theme.App" parent="Theme.MaterialComponents.*">
    ...
    <item name="colorPrimary">@color/shrine_pink_100</item>
    <item name="colorOnPrimary">@color/shrine_pink_900</item>
    <item name="textAppearanceButton">@style/TextAppearance.App.Button</item>
    <item name="shapeAppearanceSmallComponent">@style/ShapeAppearance.App.SmallComponent</item>
</style>

<style name="TextAppearance.App.Button" parent="TextAppearance.MaterialComponents.Button">
    <item name="fontFamily">@font/rubik</item>
    <item name="android:fontFamily">@font/rubik</item>
</style>

<style name="ShapeAppearance.App.SmallComponent" parent="ShapeAppearance.MaterialComponents.SmallComponent">
    <item name="cornerFamily">cut</item>
    <item name="cornerSize">4dp</item>
</style>

or using default style theme attributes, styles and theme overlays (themes all buttons but does not affect other components):

<style name="Theme.App" parent="Theme.MaterialComponents.*">
    ...
    <item name="borderlessButtonStyle">@style/Widget.App.Button.TextButton</item>
    <item name="materialButtonOutlinedStyle">@style/Widget.App.Button.OutlinedButton</item>
    <item name="materialButtonStyle">@style/Widget.App.Button</item>
</style>

<style name="Widget.App.Button.TextButton" parent="Widget.MaterialComponents.Button.TextButton">
    <item name="materialThemeOverlay">@style/ThemeOverlay.App.Button.TextButton</item>
    <item name="android:textAppearance">@style/TextAppearance.App.Button</item>
    <item name="shapeAppearance">@style/ShapeAppearance.App.SmallComponent</item>
</style>

<style name="Widget.App.Button.OutlinedButton" parent="Widget.MaterialComponents.Button.OutlinedButton">
    <item name="materialThemeOverlay">@style/ThemeOverlay.App.Button.TextButton</item>
    <item name="android:textAppearance">@style/TextAppearance.App.Button</item>
    <item name="shapeAppearance">@style/ShapeAppearance.App.SmallComponent</item>
</style>

<style name="Widget.App.Button" parent="Widget.MaterialComponents.Button">
    <item name="materialThemeOverlay">@style/ThemeOverlay.App.Button</item>
    <item name="android:textAppearance">@style/TextAppearance.App.Button</item>
    <item name="shapeAppearance">@style/ShapeAppearance.App.SmallComponent</item>
</style>

<style name="ThemeOverlay.App.Button.TextButton" parent="">
    <item name="colorPrimary">@color/shrine_pink_900</item>
</style>

<style name="ThemeOverlay.App.Button" parent="">
    <item name="colorPrimary">@color/shrine_pink_100</item>
    <item name="colorOnPrimary">@color/shrine_pink_900</item>
</style>

or using one of the styles in the layout (affects only this button):

<Button
    ...
    style="@style/Widget.App.Button"
/>

Files

Button.md

Latest commit

History

Button.md

File metadata and controls

Buttons

Using buttons

Making buttons accessible

Types

Text button

Text button examples

Adding an icon to a text button

Anatomy and key properties

Text label attributes

Container attributes

Icon attributes

Styles

Outlined button

Outlined button examples

Adding an icon to an outlined button

Anatomy and key properties

Text label attributes

Container attributes

Icon attributes

Styles

Contained button

Contained button examples

Adding an icon to a contained button

Anatomy and key properties

Text label attributes

Container attributes

Icon attributes

Styles

Toggle button

Toggle button

Toggle button examples

Implementing an icon-only toggle button

Anatomy and key properties

Selection attributes

Styles

Icon

Icon example

Theming buttons

Button theming example

Implementing button theming