material-components_material-components-android/docs/components/Button.md

Buttons

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

Contents

• Using buttons
• Text button
• Outlined button
• Filled button
• Filled button: tonal style
• Elevated 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 Theme.Material3.* 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 six types of buttons: 1. Elevated button, 2. Filled button, 3. Filled button: tonal style, 4. Outlined button, 5. Text button, 6. Toggle button

Text button

Text buttons have less visual prominence, so should be used for low emphasis actions, such as when presenting multiple options.

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.Material3.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.Material3.Button.TextButton.Icon"
/>

Anatomy and key properties

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

1. Text label
2. Icon (optional)

Text label attributes

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

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/colorOnSurface at 16% 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/colorOnSurface (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	8dp

Styles

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

Default style theme attribute: ?attr/borderlessButtonStyle

See the full list of styles and attrs.

Outlined button

Outlined buttons are for actions that need attention but aren’t the primary action, such as “See all” or “Add to cart.” This is also the button to use for giving someone the opportunity to change their mind or escape a flow.

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.Material3.Button.OutlinedButton.Icon"
/>

Anatomy and key properties

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

1. Container
2. Outline
3. Text label
4. Icon (optional)

Text label attributes

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

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/colorOnSurface at 16% 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/colorOnSurface (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	8dp

Styles

Element	Style
Default style	Widget.Material3.Button.OutlinedButton
Icon style	Widget.Material3.Button.OutlinedButton.Icon

Default style theme attribute: ?attr/materialButtonOutlinedStyle

See the full list of styles and attrs.

Filled button

Filled button's contrasting surface color makes it the most prominent button after the FAB. It’s used for final or unblocking actions in a flow.

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

Filled button examples

API and source code:

• MaterialButton
  • Class description
  • Class source

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

In the layout:

<Button
    android:id="@+id/filledButton"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:text="Filled 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.Material3.Button.

In code:

filledButton.setOnClickListener {
    // Respond to button press
}

Adding an icon to a filled button

The following example shows a filled button with an icon.

In the layout:

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

Anatomy and key properties

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

1. Container
2. Text label
3. Icon (optional)

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/textAppearanceLabelLarge

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 16% 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	8dp

Styles

Element	Style
Default style	Widget.Material3.Button
Icon style	Widget.Material3.Button.Icon
Unelevated style	Widget.Material3.Button.UnelevatedButton
Unelevated icon style	Widget.Material3.Button.UnelevatedButton.Icon

Default style theme attribute: ?attr/materialButtonStyle

See the full list of styles and attrs.

Filled button tonal style

Filled buttons: tonal style have a lighter background color and darker label color, making them less visually prominent than a regular filled button. They’re still used for final or unblocking actions in a flow, but may be better when these actions don’t require quite so much emphasis.

Filled button: tonal style examples

API and source code:

• MaterialButton
• Class description
• Class source

The following example shows a filled button: tonal style with a text label and a filled container.

In the layout:

<Button
    android:id="@+id/filledTonalButton"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:text="Filled button: Tonal style"
    style="@style/Widget.Material3.Button.TonalButton"
/>

In code:

filledTonalButton.setOnClickListener {
    // Respond to button press
}

Adding an icon to a filled button: tonal style

The following example shows a filled button: tonal style with an icon.

In the layout:

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

Anatomy and key properties

A filled button: tonal style has a text label, a filled container and an optional icon.

1. Container
2. Text label
3. Icon (optional)

Text label attributes

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

Container attributes

Element	Attribute	Related method(s)	Default value
Color	app:backgroundTint	setBackgroundColor setBackgroundTintList getBackgroundTintList	?attr/colorSecondaryContainer (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/colorOnSecondaryContainer at 16% 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/colorOnSecondaryContainer (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	8dp

Styles

Element	Style
Default style	Widget.Material3.Button.TonalButton
Icon style	Widget.Material3.Button.TonalButton.Icon

See the full list of styles and attrs.

Elevated button

Elevated buttons are essentially outlined buttons with a shadow. To prevent shadow creep, only use them when absolutely necessary, such as when the button requires visual separation from a patterned background.

Elevated button examples

API and source code:

• MaterialButton
• Class description
• Class source

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

In the layout:

<Button
    android:id="@+id/elevatedButton"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:text="Elevated button"
    style="@style/Widget.Material3.Button.ElevatedButton"
/>

In code:

elevatedButton.setOnClickListener {
    // Respond to button press
}

Adding an icon to an elevated button

The following example shows an elevated button with an icon.

In the layout:

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

Anatomy and key properties

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

1. Container
2. Text label
3. Icon (optional)

Text label attributes

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

Container attributes

Element	Attribute	Related method(s)	Default value
Color	app:backgroundTint	setBackgroundColor setBackgroundTintList getBackgroundTintList	?attr/colorSurface (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	1dp
Ripple color	app:rippleColor	setRippleColor setRippleColorResource getRippleColor	?attr/colorOnSurface at 16% 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/colorOnSurface (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	8dp

Styles

Element	Style
Default style	Widget.Material3.Button.ElevatedButton
Icon style	Widget.Material3.Button.ElevatedButton.Icon

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.Material3.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_add_24dp"
        style="@style/Widget.App.Button.OutlinedButton.IconOnly"
    />
    <Button
        ...
        app:icon="@drawable/ic_search_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.

1. Container
2. 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.Material3.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 filled 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.Material3.*">
    ...
    <item name="colorPrimary">@color/shrine_pink_100</item>
    <item name="colorOnPrimary">@color/shrine_pink_900</item>
    <item name="textAppearanceLabelLarge">@style/TextAppearance.App.Button</item>
    <item name="shapeAppearanceSmallComponent">@style/ShapeAppearance.App.SmallComponent</item>
</style>

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

<style name="ShapeAppearance.App.SmallComponent" parent="ShapeAppearance.Material3.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.Material3.*">
    ...
    <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.Material3.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.Material3.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.Material3.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"
/>