Buttons

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

Android Web check Flutter iOS

Interactive demo

This demo lets you preview the button component, its variations, and configuration options. Each tab displays a different type of button.


Usage

Buttons communicate actions that users can take. They are typically placed throughout your UI, in places like:

  • Dialogs
  • Modal windows
  • Forms
  • Cards
  • Toolbars

Principles

Identifiable

Buttons should indicate that they can trigger an action.

Findable

Buttons should be easy to find among other elements, including other buttons.

Clear

A button’s action and state should be clear.


Types

There are text, contained, and toggle buttons.

Four quadrants each showing a different type of button
1. Text button (low emphasis)
Text buttons are typically used for less important actions.

2. Outlined Button (medium emphasis)
Outlined buttons are used for more emphasis than text buttons due to the stroke.

3. Contained button (high emphasis)
Contained buttons have more emphasis, as they use a color fill and shadow.

4. Toggle button
Toggle buttons group a set of actions using layout and spacing. They’re used less often than other button types.

Anatomy

Buttons contain one required element and four optional elements.

Four quadrants, each containing a different button configuration
1. Text button
A. Text label
C. Icon (optional)

2. Outlined button
A. Text label
B. Container
C. Icon (optional)

3. Contained button
A. Text label
B. Container
C. Icon (optional)

4. Toggle button
A. Text label
C. Icon (optional)

Text label

Text buttons and contained buttons use text labels, which describe the action that will occur if a user taps a button. If a text label...

Text buttons and contained buttons use text labels, which describe the action that will occur if a user taps a button. If a text label is not used, an icon should be present to signify what the button does.

By default Material uses capitalized button text labels (for languages that have capitalization). This is to distinguish the text label from surrounding text. If a text button does not use capitalization for button text, find another characteristic to distinguish it such as color, size, or placement.

An all-capitalized text button on a card
DoUse capitalization for languages that allow capitalization.
An all-capitalized text button on a card with the text wrapping to two lines
Don'tDon’t wrap text. For maximum legibility, a text label should remain on a single line.

Hierarchy and placement

Hierarchy

A layout should contain a single prominent button that makes it clear that other buttons have less importance in the hierarchy. This high-emphasis button commands...

A single, prominent button

A layout should contain a single prominent button that makes it clear that other buttons have less importance in the hierarchy. This high-emphasis button commands the most attention.

Other buttons

An app can show more than one button in a layout at a time, so a high-emphasis button can be accompanied by medium- and low-emphasis buttons that perform less important actions. When using multiple buttons, ensure the available state of one button doesn’t look like the disabled state of another.

Pyramid diagram with three horizontal segments showing high emphasis at the top, medium in the middle, and low emphasis at the bottom
A button’s level of emphasis helps determine its appearance, typography, and placement.

Placement

Multiple button types can be used to express different emphasis levels. A floating action button (FAB) represents the primary action for a screen. Related Article...

Multiple button types can be used to express different emphasis levels.

App screen with three hierarchical types of buttons
This screen layout uses:
1. An extended floating action button for the highest emphasis
2. A contained button for high emphasis
3. A text button for low emphasis
A text button reading Hide next to a contained button reading Show
DoIn a bottom bar, when using multiple buttons, indicate the more important action by placing it in a contained button (next to a text button).
Two contained buttons next to each other, one filled with purple and the other with white
Don'tAvoid using two contained buttons next to one another if they don’t have the same fill color.
An outlined button next to a contained button
DoIn a bottom bar, when using multiple buttons, you can place a outlined button (medium emphasis) next to a contained button (high emphasis).
A text button next to an outlined button
DoWhen using multiple buttons in a bottom bar, you can place a text button (low emphasis) next to an outlined button (medium emphasis).
App screen for a hotel booking site showing a contained button next to hotel rating and price
DoUse a contained button in a bottom sheet next to other important details.
Vertically stacked buttons in a bottom bar
Don'tDon’t place a button below another button if there is space to place them side by side.

Behavior

Scaling and adaptation

When scaling layouts for large screen devices, buttons can adapt their visual presentation, alignment, and arrangement to fit different contexts and user needs.

When scaling layouts for large screen devices, buttons can adapt their visual presentation, alignment, and arrangement to fit different contexts and user needs.

Container properties

Buttons are typically placed in containers such as cards or dialogs. As a parent container scales to adapt to different screen sizes, a button’s size, position, and alignment within the container can also change.

Buttons can be aligned left, right, or center as the parent container scales.

Button centered at the bottom of a card

A button’s position and size should scale in relationship to its container.

Button remaining full-width on a larger card

Arrangement

Define the position and alignment of button elements such as text and icons in relationship to their container. For example, the icon and text label within a button remain centered and anchored to each other as the button width scales.

DoGroup internal elements so that they scale appropriately. Icons and text labels remain centered when button width increases.
Don'tDon’t ungroup elements inside of a button container. This can lead to unwanted movement, such as the icon and label anchoring to opposite sides of the button.

The size and placement of buttons can change as parent containers, such as cards, adapt for larger screens.

Buttons appearing with different dimensions in two different size cards
Two buttons scaling to accommodate different component sizes.

Text button

Usage

Text buttons are typically used for less-pronounced actions, including those located: In cards, text buttons help maintain an emphasis on card content. A button’s text...

Text buttons are typically used for less-pronounced actions, including those located:

  • In dialogs
  • In cards

In cards, text buttons help maintain an emphasis on card content.

Text button on a card
Text button
Text button on a snackbar
Use a text button in snackbars.
Text button on top of an image
A text button against an image background.

Text label

A button’s text label is the most important element on a button, as it communicates the action that will be performed when the user touches it.

Screen for a restaurant reservation app with a text label reading Reserve
Text label using a distinct action.
Text label in camelcase in a purple bolded style in a layout with other text chips and titles in grey and white
CautionText labels need to be distinct from other elements. If the text label isn’t fully capitalized, it should use a different color, style, or layout from other text.
Screen for a restaurant reservation app with a text label that says RESERVE TABLE AT THIS CAFE
Don'tAvoid text labels that are too long. They should be concise.

Placement

Text buttons are often embedded in contained components like cards and dialogs, in order to relate themselves to the component in which they appear. Because...

Text buttons are often embedded in contained components like cards and dialogs, in order to relate themselves to the component in which they appear. Because text buttons don’t have a container, they don’t distract from nearby content.

Dialog with two text buttons in the lower right hand corner
Dialogs use text buttons because the absence of a container helps unify the action with the dialog text. Align text buttons to the right edge for left-to-right scripts.
Dialog with a text button left aligned with the paragraph above it
Text buttons minimize distraction from card content.

States

Text buttons can be placed in front of a variety of backgrounds. Until the button is interacted with, its container isn’t visible. To maintain accessibility,...

Text buttons can be placed in front of a variety of backgrounds. Until the button is interacted with, its container isn’t visible.

To maintain accessibility, Material Design provides baseline opacity values for the color overlays used by states. A brand can adjust opacity values to suit its color scheme.

5-part image demonstrating different states: Enabled, disabled, hover, focused, and pressed
Text button states

Outlined button

Usage

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

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

Alternatives

Outlined buttons are also a lower emphasis alternative to contained buttons, or a higher emphasis alternative to text buttons.

Outlined button on a card

Container

Outlined buttons display a stroke around a text label. Stroke can be represented in different ways: In a resting state, outlined buttons should display containment...

Outlined buttons display a stroke around a text label. Stroke can be represented in different ways:

  • Set a button’s width to be the size of the text label, with 16dp padding on the left and right
  • Set the button’s relative position to the responsive layout grid

In a resting state, outlined buttons should display containment with a stroke and no fill.

Screen for shopping app with outlined button reading “Add to Cart”
Outlined button
Outlined button with the label fitting well within the outline
DoAn outlined button’s width is dynamically set to fit the text label.
Outlined button with the label falling outside the outline
Don'tAn outlined button’s width shouldn’t be narrower than the button’s text length.
Outlined button in front of image
CautionDistinguish text when using outlined buttons in front of images. This image uses a light purple scrim to make text easy to read in the outlined button.

States

Outlined buttons can be placed on top of a variety of backgrounds. Its container is transparent and until the button is interacted with, a color...

Outlined buttons can be placed on top of a variety of backgrounds. Its container is transparent and until the button is interacted with, a color isn’t visible.

To maintain accessibility, Material Design provides baseline opacity values for the color overlays used by states. A brand can adjust opacity values to suit its color scheme.

5 Outlined button states in a diagram: enabled, disabled, hover, focused, and pressed
Outlined button states

Contained button

Usage

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

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

Contained button on a card
A contained button
Contained button with label “See all” written in sentence case
DoText labels can be written in sentence case, as long as the button is clearly distinguishable from elements around it.

Container

Contained buttons display a container around a text label. Containers can be represented in different ways: Contained buttons should display containers with a solid color....

Contained buttons display a container around a text label. Containers can be represented in different ways:

  • Set container width to the size of the text label with 16dp padding on the left and right
  • Set the container’s relative position to the responsive layout grid

Contained buttons should display containers with a solid color.

Contained button with purple background
A contained button with solid color
Contained button with label that fits within the button
DoA button container’s width is dynamically set to fit its text label.
Contained button with label that falls outside of the button.
Don'tA button container’s width shouldn’t be narrower than its text.

Button container width can be set according to the responsive layout grid.

Contained button that is aligned with the right and left side of a text paragraph
Contained button in a responsive layout grid

Icon

Contained buttons can place icons next to text labels to both clarify an action and call attention to a button.

Contained buttons can place icons next to text labels to both clarify an action and call attention to a button.

Shopping cart icon on an “Add to cart” contained button
DoUse icons that clearly communicate their meaning.
Icon vertically stacked on top of a text label
Don'tDon’t vertically align an icon and text in the center of a contained button.
Contained button with both a leave and a cancel icon
Don'tDon’t use two icons in the same button.

Shadow & elevation

Buttons at higher elevations typically appear more prominent in a design. On press, elevated buttons lift up and the container displays touch feedback.

Buttons at higher elevations typically appear more prominent in a design. On press, elevated buttons lift up and the container displays touch feedback.

Contained button with a shadow below it
Higher elevation increases the prominence of a contained button.

States

Recommended opacity values for button container fill colors can be found in the states guidelines. An app can alter the overlay values of the button...

Recommended opacity values for button container fill colors can be found in the states guidelines. An app can alter the overlay values of the button to suit a brand’s color palette.

5 contained button states diagrammed: enabled, disabled, hover, focused, and pressed
Contained button states

Toggle button

Usage

Toggle buttons can be used to group related options. To emphasize groups of related toggle buttons, a group should share a common container. Only one...

Toggle buttons can be used to group related options. To emphasize groups of related toggle buttons, a group should share a common container.

Selected action

Only one option in a group of toggle buttons can be selected and active at a time. Selecting one option deselects any other.

A row of toggle buttons in a text editing UI
These toggle buttons present options for aligning text to the left, right, and center.
Heart icon buttons on a photo grid. One is filled and three are outlined.
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.

States

A toggle button’s state makes it clear which button is active. Hover and focus states express the available selection options for buttons in a toggle...

Active and available toggle buttons

A toggle button’s state makes it clear which button is active. Hover and focus states express the available selection options for buttons in a toggle group.

Disabled toggle buttons

Toggle buttons that cannot be selected can either be given a disabled state, or be hidden.

6 toggle button states in a diagram: enabled, disabled, hover, focus, active, and pressed
Toggle button states

Theming

Crane Material theme

This travel app’s buttons have been customized using Material Theming. Areas of customization include color, typography, and shape. Crane is a travel app that uses...

Color

Crane’s buttons use custom color on two elements: the container and text.

Diagram of button with two-color mapping
Element Category Attribute Value
Container Primary Color
Opacity
#5C1349
100%
Text On Primary Color
Opacity
#FFFFFF
100%

Shape

Crane’s button containers have custom corner shapes, with a 50% corner radius. *Crane buttons are in the small component shape category, and they use a custom size.

Diagram of a button with shaped corners that follow the contour of half of a perfect circle
Element Category Attribute Value
Container Override* Family
Size
Rounded
50%

Fortnightly Material theme

This news app’s buttons have been customized using Material Theming. Areas of customization include color and typography. Fortnightly is a news app that uses Material...

Color

Fortnightly’s buttons use custom color on two elements: background and text.

Diagram of button with color mapping of white background and purple text
Element Category Attribute Value
Background Background Color
Opacity
#FFFFFF
100%
Text Primary Color
Opacity
#661FFF
100%

Typography

Fortnightly’s buttons use custom typography for the button text.

Diagram of button using Material’s type scale
Element Category Attribute Value
Text Button Typeface
Font
Size
Case
Libre Franklin
ExtraBold
14
Sentence case

Rally Material theme

This personal finance app’s buttons have been customized using Material Theming. Areas of customization include color and typography. Rally is a personal finance app that...

Color

Rally’s buttons use custom color on two elements: background and text.

Diagram of buttons with two-color mapping of grey surface and white text
Element Category Attribute Value
Background Surface Color
Opacity
#3C3C46
100%
Text Primary Color
Opacity
#FFFFFF
100%

Typography

Rally’s buttons use custom typography for the button text.

Diagram of button using Material’s type scale
Element Category Attribute Value
Text Button Typeface
Font
Size
Case
Roboto Condensed
Bold
14
All caps

Posivibes Material theme

This social media app’s buttons have been customized using Material Theming. Areas of customization include color, typography, and shape. The Material Design color system can...

This social media app’s buttons have been customized using Material Theming. Areas of customization include color, typography, and shape.

Customized buttons with a black outline and black, bold typography
Posivibe’s customized buttons

Color

Posivibe’s buttons use custom color on two elements: the container stroke and text.

Diagram of button with two-color mapping of black container stroke and black text
Element Category Attribute Value
Container stroke Secondary Color
Opacity
#000000
100%
Text Primary Color
Opacity
#000000
100%

Shape

Posivibe’s button containers have custom corner shapes, with 0dp long cut corners.

Diagram of button with sharp corners
Element Category Attribute Value
Container Small component Family
Size
Cut
0;0;0;0dp

Reply Material theme

This email app’s buttons have been customized using Material Theming. Areas of customization include color and typography. Reply is an email app that uses Material...

Color

Reply’s buttons use custom color on four elements: background, icon, icon fill, and text.

Diagram of icon button with three-color mapping
Element Category Attribute Value
Background Surface Color
Opacity
#FFFFFF
100%
Icon Primary Color
Opacity
#344955
100%
Icon fill On Primary Color
Opacity
#344955
30%
Text Primary Color
Opacity
#344955
100%

Typography

Reply’s buttons use custom typography for the button text.

Diagram of button using Material’s type scale
Element Category Attribute Value
Text Button Typeface
Font
Size
Case
Work Sans
ExtraBold
15
All caps

Shrine Material theme

This retail app’s buttons have been customized using Material Theming. Areas of customization include color, typography, and shape. Shrine is a lifestyle and fashion brand...

Color

Shrine’s buttons use custom color on three elements: the container, icon, and text.

Diagram of icon button with three-color mapping
Element Category Attribute Value
Container Primary Color
Opacity
#FEDBD0
100%
Icon On Primary Color
Opacity
#442C2E
100%
Text On Primary Color
Opacity
#442C2E
100%

Shape

Shrine’s button containers have custom corner shapes, with cut corner shapes.

Diagram of button with cut angular corners
Element Category Attribute Value
Container Small component Family
Size
Cut
4dp; 4dp; 4dp; 4dp

Specs

Contained button

  • Measurement C
  • Measurement 36
  • Measurement min-width: 64dp
  • Measurement 16
  • Measurement 16
 

Contained button with icon

  • Measurement 8
  • Measurement 12
  • Measurement 16
  • Measurement 36
  • Measurement min-width: 64dp
  • Measurement C
  • 1818
 

Outlined button

  • Measurement C
  • Measurement 16
  • Measurement 16
  • Measurement 36
  • Measurement min-width: 64dp
  • Measurement 1
 

Text button

  • Measurement 36
  • Measurement min-width: 64dp
  • Measurement 8
  • Measurement 8
  • Measurement C
 

Toggle buttons

  • Measurement 48
  • Measurement 12
  • Measurement 12
  • Measurement 12
  • Measurement 12
  • Measurement 48
  • Measurement 1
  • 2424
 

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

"Button types - text, outlined, contained and toggle."

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:

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

"Text button with purple text 'Text button' over a white background."

In the layout:

In code:

Adding an icon to a text button

The following example shows a text button with an icon.

"Text button with purple text 'Text button' and '+' icon over a white
background."

In the layout:

Anatomy and key properties

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

Text button anatomy diagram

  1. Text label
  2. Icon

Text label attributes

ElementAttributeRelated method(s)Default value
Text labelandroid:textsetText
getText
null
Colorandroid:textColorsetTextColor
getTextColor
?attr/colorPrimary (see all states)
Typographyandroid:textAppearancesetTextAppearance?attr/textAppearanceButton

Container attributes

ElementAttributeRelated method(s)Default value
Colorapp:backgroundTintsetBackgroundColor
setBackgroundTintList
getBackgroundTintList
@android:color/transparent (see all states)
Stroke colorapp:strokeColorsetStrokeColor
setStrokeColorResource
getStrokeColor
null
Stroke widthapp:strokeWidthsetStrokeWidth
setStrokeWidthResource
getStrokeWidth
0dp
Shapeapp:shapeAppearancesetShapeAppearanceModel
getShapeAppearanceModel
?attr/shapeAppearanceSmallComponent
Elevationapp:elevationsetElevation
getElevation
0dp
Ripple colorapp:rippleColorsetRippleColor
setRippleColorResource
getRippleColor
?attr/colorPrimary at 12% opacity (see all states)

Icon attributes

ElementAttributeRelated method(s)Default value
Iconapp:iconsetIcon
setIconResource
getIcon
null
Colorapp:iconTintsetIconTint
setIconTintResource
getIconTint
?attr/colorPrimary (see all states)
Sizeapp:iconSizesetIconSize
getIconSize
wrap_content
Gravity (position relative to text label)app:iconGravitysetIconGravity
getIconGravity
start
Padding (space between icon and text label)app:iconPaddingsetIconPadding
getIconPadding
4dp

Styles

ElementStyle
Default styleWidget.MaterialComponents.Button.TextButton
Icon styleWidget.MaterialComponents.Button.TextButton.Icon
Full Width ButtonsWidget.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:

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

"Outlined button with purple text 'Outlined button' and grey border over a
white background."

In the layout:

In code:

Adding an icon to an outlined button

The following example shows an outlined button with an icon.

"Outlined button with purple text 'Outlined button', grey border and '+' icon
over a white background."

In the layout:

Anatomy and key properties

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

Outlined button anatomy diagram

  1. Text label
  2. Container
  3. Icon

Text label attributes

ElementAttributeRelated method(s)Default value
Text labelandroid:textsetText
getText
null
Colorandroid:textColorsetTextColor
getTextColor
?attr/colorPrimary (see all states)
Typographyandroid:textAppearancesetTextAppearance?attr/textAppearanceButton

Container attributes

ElementAttributeRelated method(s)Default value
Colorapp:backgroundTintsetBackgroundColor
setBackgroundTintList
getBackgroundTintList
@android:color/transparent (see all states)
Stroke colorapp:strokeColorsetStrokeColor
setStrokeColorResource
getStrokeColor
?attr/colorOnSurface at 12% opacity (see all states)
Stroke widthapp:strokeWidthsetStrokeWidth
setStrokeWidthResource
getStrokeWidth
1dp
Shapeapp:shapeAppearancesetShapeAppearanceModel
getShapeAppearanceModel
?attr/shapeAppearanceSmallComponent
Elevationapp:elevationsetElevation
getElevation
0dp
Ripple colorapp:rippleColorsetRippleColor
setRippleColorResource
getRippleColor
?attr/colorPrimary at 12% opacity (see all states)

Icon attributes

ElementAttributeRelated method(s)Default value
Iconapp:iconsetIcon
setIconResource
getIcon
null
Colorapp:iconTintsetIconTint
setIconTintResource
getIconTint
?attr/colorPrimary (see all states)
Sizeapp:iconSizesetIconSize
getIconSize
wrap_content
Gravity (position relative to text label)app:iconGravitysetIconGravity
getIconGravity
start
Padding (space between icon and text label)app:iconPaddingsetIconPadding
getIconPadding
4dp

Styles

ElementStyle
Default styleWidget.MaterialComponents.Button.OutlinedButton
Icon styleWidget.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:

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

"Contained button with white text 'Contained button' and purple container over
a white background."

In the layout:

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:

Adding an icon to a contained button

The following example shows a contained button with an icon.

"Contained button with white text 'Contained button', purple container and '+'
icon over a white background."

In the layout:

Anatomy and key properties

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

Contained button anatomy diagram

  1. Text label
  2. Container
  3. Icon

Text label attributes

ElementAttributeRelated method(s)Default value
Text labelandroid:textsetText
getText
null
Colorandroid:textColorsetTextColor
getTextColor
?attr/colorOnPrimary (see all states)
Typographyandroid:textAppearancesetTextAppearance?attr/textAppearanceButton

Container attributes

ElementAttributeRelated method(s)Default value
Colorapp:backgroundTintsetBackgroundColor
setBackgroundTintList
getBackgroundTintList
?attr/colorPrimary (see all states)
Stroke colorapp:strokeColorsetStrokeColor
setStrokeColorResource
getStrokeColor
null
Stroke widthapp:strokeWidthsetStrokeWidth
setStrokeWidthResource
getStrokeWidth
0dp
Shapeapp:shapeAppearancesetShapeAppearanceModel
getShapeAppearanceModel
?attr/shapeAppearanceSmallComponent
Elevationapp:elevationsetElevation
getElevation
2dp
Ripple colorapp:rippleColorsetRippleColor
setRippleColorResource
getRippleColor
?attr/colorOnPrimary at 24% opacity (see all states)

Icon attributes

ElementAttributeRelated method(s)Default value
Iconapp:iconsetIcon
setIconResource
getIcon
null
Colorapp:iconTintsetIconTint
setIconTintResource
getIconTint
?attr/colorOnPrimary (see all states)
Sizeapp:iconSizesetIconSize
getIconSize
wrap_content
Gravity (position relative to text label)app:iconGravitysetIconGravity
getIconGravity
start
Padding (space between icon and text label)app:iconPaddingsetIconPadding
getIconPadding
4dp

Styles

ElementStyle
Default styleWidget.MaterialComponents.Button
Icon styleWidget.MaterialComponents.Button.Icon
Unelevated styleWidget.MaterialComponents.Button.UnelevatedButton
Unelevated icon styleWidget.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

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

Toggle button examples

API and source code:

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

"Toggle button example for Android with text labels - 'Button 1', 'Button 2'
and 'Button 3' - and grey/purple borders over a white
background."

In the layout:

In code:

Implementing an icon-only toggle button

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

"Toggle buttons with icons - heart, eye and bell - and grey/purple borders
over a white background."

In res/values/styles.xml:

In the layout:

Anatomy and key properties

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

Toggle button anatomy

  1. Container
  2. Icon

Selection attributes

ElementAttributeRelated method(s)Default value
Single selectionapp:singleSelectionsetSingleSelection
isSingleSelection
false
Selection requiredapp:selectionRequiredsetSelectionRequired
isSelectionRequired
false

Styles

ElementStyle
Default styleWidget.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:

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.

Toggle icon example showing 4 images, heart icon in the upper-right corner of
each image

In the layout:

In res/drawable/sl_favourite_24dp.xml:

In code:

Theming buttons

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

Button theming example

API and source code:

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

"Button theming with three buttons - text, outlined and contained - with pink
color theming and cut corners."

Implementing button theming

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

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

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

No Android implementation guidance available

Using buttons

Installation

Styles

JavaScript instantiation

The button will work without JavaScript, but you can enhance it to have a ripple effect by instantiating MDCRipple on the root element. See MDC Ripple for details.

Note: See Importing the JS component for more information on how to import JavaScript.

Making buttons accessible

Material Design spec advises that touch targets should be at least 48 x 48 px. To meet this requirement, add the following to your button:

Note: The outer mdc-touch-target-wrapper element is only necessary if you want to avoid potentially overlapping touch targets on adjacent elements (due to collapsing margins).

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 example

Text button example

Text button with icon example

Text button with bookmark icon example

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 example

Outlined button example

Outlined button with icon example

Outlined button with bookmark icon

Contained button

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

Contained button example

Contained button example

Note: mdc-button--raised is applied for a contained button with elevation, and mdc-button--unelevated is applied for a contained button flush with the surface.

Contained button with icon example

Contained button with a bookmark icon

Toggle button

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

There are two types of toggle buttons:

toggle button group

MDC Web currently does not support toggle button groups.

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.

For more details, see the mdc-icon-button page.

Other Variants

Icon

We recommend using Material Icons from Google Fonts:

However, you can also use SVG, Font Awesome, or any other icon library you wish.

To add an icon, add an element with the mdc-button__icon class inside the button element and set the attribute aria-hidden="true". The icon is set to 18px to meet legibility requirements.

It's also possible to use an SVG icon:

Trailing Icon

Certain icons make more sense to appear after the button's text label rather than before. This can be accomplished by putting the icon markup after the mdc-button__label element.

Note: The mdc-button__label element is required in order for the trailing icon to be styled appropriately.

Disabled

To disable a button, add the disabled attribute directly to the <button>, or set the disabled attribute on the <fieldset> containing the button. Disabled buttons cannot be interacted with and have no visual interaction effect.

Button theming example

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

Button theming with three buttons - text, contained, and outlined - with Shrine theming.

Theming with Sass variables

Before importing any MDC Web modules, set the theme colors in your Sass file:

In this case we also want to customize the label color of the text and outlined buttons, to fulfill color contrast requirements. Assuming that you've applied the custom-text-button and custom-outlined-button classes to your buttons:

Theming with CSS custom properties

If you want to customize the theme for buttons without changing the theme across the app, you can also use CSS custom properties:

For a more information on theming in general, see this page.

API

CSS classes

CSS ClassDescription
mdc-buttonMandatory. Defaults to a text button that is flush with the surface.
mdc-button__rippleMandatory. Indicates the element which shows the ripple styling.
mdc-button--raisedOptional. Styles a contained button that is elevated above the surface.
mdc-button--unelevatedOptional. Styles a contained button that is flush with the surface.
mdc-button--outlinedOptional. Styles an outlined button that is flush with the surface.
mdc-button--icon-leadingOptional. Styles a button with a leading icon.
mdc-button--icon-trailingOptional. Styles a button with a trailing icon.
mdc-button__labelRecommended.* Indicates the element containing the button's text label.
mdc-button__iconOptional. Indicates the element containing the button's icon.

Note: The mdc-button__label element is required for buttons with a trailing icon, but it is currently optional for buttons with no icon or a leading icon. In the latter cases, it is acceptable for the text label to simply exist directly within the mdc-button element.
However, the mdc-button__label class may become mandatory for all cases in the future so we recommend always including it.

Sass mixins

To customize a button's color and properties, you can use the following mixins.

Basic Sass mixins

MDC Button uses MDC Theme's primary color by default. Use the following mixins to customize it.

MixinDescription
filled-accessible($container-fill-color)Sets the container fill color for a contained (raised or unelevated) button, and updates the button's ink, icon, and ripple colors to meet accessibility standards

Advanced Sass mixins

These mixins will override the color of the container, ink, outline or ripple. It is up to you to ensure your button meets accessibility standards.

MixinDescription
container-fill-color($color-or-map)If a color is passed, sets the default container fill color to the given color. If a map is passed whose keys are in the set {default, hover, focus, pressed, disabled}, sets the color in each specified state to its corresponding value.
icon-color($color-or-map)If a color is passed, sets the default icon color to the given color. If a map is passed whose keys are in the set {default, hover, focus, pressed, disabled}, sets the color in each specified state to its corresponding value.
ink-color($color-or-map)If a color is passed, sets the default ink color to the given color, and sets the icon color to the given color unless icon-color is also used. If a map is passed whose keys are in the set {default, hover, focus, pressed, disabled}, sets the color in each specified state to its corresponding value.
density($density-scale)Sets density scale for button. Supported density scale values (-3, -2, -1, 0).
height($height)Sets custom height for button.
shape-radius($radius, $density-scale, $rtl-reflexive)Sets rounded shape to button with given radius size. $density-scale is only required when $radius value is in percentage unit, defaults to $density-default-scale. Set $rtl-reflexive to true to flip radius values in RTL context, defaults to false.
horizontal-padding($padding)Sets horizontal padding to the given number.
outline-color($color-or-map)If a color is passed, sets the default outline color to the given color. If a map is passed whose keys are in the set {default, hover, focus, pressed, disabled}, sets the color in each specified state to its corresponding value.
outline-width($width, $padding)Sets the outline width to the given number (defaults to 2px) and adjusts padding accordingly. $padding is only required in cases where $horizontal-padding is also included with a custom value.
No Web implementation guidance available

Using buttons

Before you can use Material buttons, you need to import the Material Components package for Flutter: package:flutter/material.dart.

You need to be using a MaterialApp.

For more information on getting started with the Material for Flutter, go to the Flutter Material library page.

Making buttons accessible

Flutter's APIs support accessibility setting for large fonts, screen readers, and sufficient contrast. For more information, go to Flutter's accessibility and internationalization pages.

For more guidance on writing labels, go to our page on how to write a good accessibility label.

Types

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

Four button types shown

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:

TextButton

"Text button examples with purple text 'Text button' and '+' icon over a white background."

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

The following example shows a text button with an icon.

Anatomy and key properties for text button

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

Text button anatomy diagram

  1. Text label
  2. Container
  3. Icon

Text label for text button

 Property
Text labelchild (label on TextButton.icon)
ColorforegroundColor on TextButton.style
Disabled Text ColorforegroundColor on TextButton.style
Typographystyle on child or label

Container for text button

 Property
ColorbackgroundColor on TextButton.style
Shapeshape on TextButton.style
Elevationelevation on TextButton.style
Ripple coloroverlayColor on TextButton.style

Icon for text button

 Property
Iconicon
Colorcolor on icon
Sizesize on icon

Constructors for text button

 Constructor
Default constructorTextButton()
Icon constructorTextButton.icon()

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:

OutlinedButton

"Outlined button examples with purple text 'Text button' and '+' icon and grey border over a white background."

The following example shows an outlined button with an icon.

Anatomy and key properties for outlined button

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

Outlined button anatomy diagram

  1. Text label
  2. Container
  3. Icon

Text label for outlined button

 Property
Text labelchild (label on OutlinedButton.icon)
ColorforegroundColor on OutlinedButton.style
Typographystyle on child or label

Container for outlined button

 Property
ColorbackgroundColor on OutlinedButton.style
Stroke colorside.color on OutlinedButton.style
Stroke widthside.width on OutlinedButton.style
Shapeshape on OutlinedButton.style
Elevationelevation on OutlinedButton.style
Ripple coloroverlayColor on OutlinedButton.style

Icon for outlined button

 Property
Iconicon
Colorcolor on icon
Sizesize on icon

Constructors for outlined button

 Constructor
Default constructorOutlinedButton
Icon constructorOutlinedButton.icon

Contained button

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

Contained button examples

API and source code:

ElevatedButton

"Contained button examples with white text 'Contained button' and '+' icon over a purple background."

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

The following example shows a contained button with an icon.

Anatomy and key properties for elevated button

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

Contained button anatomy diagram

  1. Text label
  2. Container
  3. Icon

Text label for elevated button

 Property
Text labelchild (label on ElevatedButton.icon)
ColorforegroundColor on ElevatedButton.style
Typographystyle on child or label

Container for elevated button

 Property
ColorbackgroundColor on ElevatedButton.style
Shapeshape on ElevatedButton.style
Elevationelevation on ElevatedButton.style
Ripple coloroverlayColor on ElevatedButton.style

Icon for elevated button

 Property
Iconicon
Colorcolor on icon
Sizesize on icon

Constructors for elevated button

 Constructor
Default constructorElevatedButton
Icon constructorElevatedButton.icon

Toggle button

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

There are two types of toggle buttons:

Toggle

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

Toggle button examples

API and source code:

ToggleButtons

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

"Toggle button example with text labels - 'Button 1', 'Button 2' and 'Button 3' - and grey/purple borders over a white background."

In the state:

In the widget hierarchy:

Implementing an icon-only toggle button

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

"Toggle button example for Flutter with icons - heart, eye and bell - and grey/purple borders over a white background."

Anatomy and key properties

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

Toggle button anatomy

  1. Container
  2. Icon

Selection

 Property
Selection state of each buttonisSelected

Constructors

 Constructor
Default constructorToggleButtons

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:

IconButton

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

Toggle button of 4 images, each image with favorite icon in top-right

In the state:

In the widget hierarchy:

Theming buttons

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

Button theming example

The following example shows text, outlined and contained button types with the Material Shrine Theme.

Example of buttons with Shrine theme

No Flutter implementation guidance available

Using buttons

Installing

In order to use Material buttons, first add the Buttons subspec to your Podfile:

Then, run the installer:

After that, import the relevant target or file and initialize your button.

Swift

Objective-C

Making Buttons accessible

To help ensure your buttons are accessible to as many users as possible, please be sure to review the following recommendations:

Set -accessibilityLabel

Set an appropriate accessibilityLabel value if your button does not have a title. This is often the case with Floating Action Button instances which typically only have an icon.

Swift

Objective-C

Minimum touch size

Make sure that your buttons have a minimum touch area. The Material spec for buttons calls for buttons that have a visual height of 36 and that touch areas should be at least 48 points high and 48 wide.

Set the touch size

To keep a button's visual sizes small with larger touchable areas, set the hitAreaInsets to a negative value. Be careful to maintain sufficient distance between the button touch targets. This will allow your button to have a large enough touch target while maintaining the desired visual appearance. For more see the Touch and click targets in the spec.

Swift

Objective-C

Set the minimum visual size of the button

Set your buttons to have a minimum size. Though there are some exceptions, Material Buttons guidelines typically recommend a minimum height of 36 points and a minimum width of 64 points.

Swift

Objective-C

Using accessibilityHint

Apple rarely recommends using the accessibilityHint because the label should already be clear enough to indicate what will happen. Before you consider setting an -accessibilityHint consider if you need it or if the rest of your UI could be adjusted to make it more contextually clear.

A well-crafted, thoughtful user interface can remove the need for accessibilityHint in most situations. Examples for a selection dialog to choose one or more days of the week for a repeating calendar event:

  • (Good) The dialog includes a header above the list of days reading, "Event repeats weekly on the following day(s)." The list items do not need accessibilityHint values.
  • (Bad) The dialog has no header above the list of days. Each list item (representing a day of the week) has the accessibilityHint value, "Toggles this day."

Types

There are four types of buttons: 1. Text button 2. Outlined button 3. Contained button 4. Toggle button (not supported in iOS)"

Example of the four button types

All Material buttons are implemented by MDCButton, a subclass of UIButton.

Text button

An animated Material Design 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 example

To use a text button use the text button theming method on the MDCButton theming extension. For more information on theming extensions see the Theming section.

Swift

Objective-C

Anatomy and key properties

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

Text button anatomy diagram

  1. Text label
  2. Container
  3. Icon

Text label attributes

 AttributeRelated method(s)Default value
Text labeltitleLabelsetTitle:forState:
titleForState:
nil
ColortitleLabel.textColorsetTitleColor:forState:
titleColorForState:
Primary color
TypographytitleLabel.fontsetFont: and font on titleLabelButton

Container attributes

 AttributeRelated method(s)Default value
ColorbackgroundColorsetBackgroundColor:forState:
backgroundColorForState
UIColor.clearColor
Stroke colorsetBorderColor:forState:
borderColorForState:
nil
Stroke widthsetBorderWidth:forState:
borderWidthForState:
0
Ripple colorinkColorsetInkColor
inkColor
Primary color at 12% opacity

Icon attributes

 AttributeRelated method(s)Default value
IconimageViewsetImage:forState:
imageForState:
nil
ColorimageView.tintColorsetImageViewTintColor:forState:
imageViewTintColorForState:
nil

Outlined button

An animated Material Design 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 example

To achieve an outlined button use the outlined button theming method on the MDCButton theming extension. To access the theming extension see the Theming section.

Swift

Objective-C

Anatomy and Key properties

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

Outlined button anatomy diagram

  1. Text label
  2. Container
  3. Icon

Text label attributes

 AttributeRelated method(s)Default value
Text labeltitleLabelsetTitle:forState:
titleForState:
nil
ColortitleLabel.textColorsetTitleColor:forState:
titleColorForState:
Primary color
TypographytitleLabel.fontsetFont: and font on titleLabelButton

Container attributes

 AttributeRelated method(s)Default value
ColorbackgroundColorsetBackgroundColor:forState:
backgroundColorForState
UIColor.clearColor
Stroke colorsetBorderColor:forState:
borderColorForState:
On surface color at 12% opacity
Stroke widthsetBorderWidth:forState:
borderWidthForState:
1
Ripple colorinkColorsetInkColor
inkColor
Primary color at 12% opacity

Icon attributes

 AttributeRelated method(s)Default value
IconimageViewsetImage:forState:
imageForState:
nil
ColorimageView.tintColorsetImageViewTintColor:forState:
imageViewTintColorForState:
nil

Contained button

An animated Material Design contained button.

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

Contained button example

Contained buttons are implemented by MDCButton. To achieve a contained button use the contained button theming method on the MDCButton theming extension. To access the theming extension see the Theming section.

Swift

Objective-C

Anatomy and Key properties

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

Contained button anatomy diagram

  1. Text label
  2. Container
  3. Icon

Text label attributes

 AttributeRelated method(s)Default value
Text labeltitleLabelsetTitle:forState:
titleForState:
nil
ColortitleLabel.textColorsetTitleColor:forState:
titleColorForState:
On primary color
TypographytitleLabel.fontsetFont: and font on titleLabelButton

Container attributes

 AttributeRelated method(s)Default value
ColorbackgroundColorsetBackgroundColor:forState:
backgroundColorForState
Primary color
Stroke colorsetBorderColor:forState:
borderColorForState:
nil
Stroke widthsetBorderWidth:forState:
borderWidthForState:
nil
Ripple colorinkColorsetInkColor
inkColor
On primary color at 12% opacity

Icon attributes

 AttributeRelated method(s)Default value
IconimageViewsetImage:forState:
imageForState:
nil
ColorimageView.tintColorsetImageViewTintColor:forState:
imageViewTintColorForState:
nil

Theming

You can theme an MDCButton to match any of the Material Button styles using theming extensions. Learn more about theming extensions. Below is a screenshot of Material Buttons with the Material Design Shrine theme:

Shrine buttons

Buttons theming example

To make use of the theming methods shown in the examples above install the Buttons theming extensions with Cocoapods. First, add the following line to your Podfile:

Then run the installer:

Next, import the Buttons theming target and initialize a button.

Swift

Objective-C

From there, use the theming methods from the examples to achieve your preferred button style.

No iOS implementation guidance available

Up next