# ButtonKt
Added in 1.3.0
*** ** * ** ***
```
public final class ButtonKt
```
*** ** * ** ***
## Summary
| ### Public methods |
|---|---|
| `static final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement` | `https://developer.android.com/reference/androidx/wear/protolayout/material3/ButtonKt#(androidx.wear.protolayout.material3.MaterialScope).avatarButton(androidx.wear.protolayout.ModifiersBuilders.Clickable,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Function1,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.ButtonColors,androidx.wear.protolayout.material3.AvatarButtonStyle,kotlin.Int,androidx.wear.protolayout.ModifiersBuilders.Padding)( @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/material3/MaterialScope receiver, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/ModifiersBuilders.Clickable onClick, @https://developer.android.com/reference/androidx/annotation/NonNull Function1<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/material3/MaterialScope, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement> labelContent, @https://developer.android.com/reference/androidx/annotation/NonNull Function1<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/material3/MaterialScope, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement> avatarContent, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/modifiers/LayoutModifier modifier, Function1<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/material3/MaterialScope, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement> secondaryLabelContent, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/DimensionBuilders.ContainerDimension height, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/ModifiersBuilders.Corner shape, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/material3/ButtonColors colors, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/material3/AvatarButtonStyle style, int horizontalAlignment, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/ModifiersBuilders.Padding contentPadding )` Opinionated ProtoLayout Material3 pill shape avatar button that offers up to three slots to take content representing vertically stacked label and secondary label, and an image (avatar) next to it. |
| `static final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement` | `https://developer.android.com/reference/androidx/wear/protolayout/material3/ButtonKt#(androidx.wear.protolayout.material3.MaterialScope).button(androidx.wear.protolayout.ModifiersBuilders.Clickable,kotlin.Function1,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.ButtonColors,kotlin.Function1,androidx.wear.protolayout.material3.ButtonStyle,kotlin.Int,androidx.wear.protolayout.ModifiersBuilders.Padding)( @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/material3/MaterialScope receiver, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/ModifiersBuilders.Clickable onClick, @https://developer.android.com/reference/androidx/annotation/NonNull Function1<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/material3/MaterialScope, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement> labelContent, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/modifiers/LayoutModifier modifier, Function1<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/material3/MaterialScope, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement> secondaryLabelContent, Function1<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/material3/MaterialScope, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement> iconContent, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/DimensionBuilders.ContainerDimension width, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/DimensionBuilders.ContainerDimension height, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/ModifiersBuilders.Corner shape, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/material3/ButtonColors colors, Function1<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/material3/MaterialScope, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement> backgroundContent, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/material3/ButtonStyle style, int horizontalAlignment, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/ModifiersBuilders.Padding contentPadding )` Opinionated ProtoLayout Material3 pill shape button that offers up to three slots to take content representing vertically stacked label and secondary label, and an icon next to it. |
| `static final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement` | `https://developer.android.com/reference/androidx/wear/protolayout/material3/ButtonKt#(androidx.wear.protolayout.material3.MaterialScope).compactButton(androidx.wear.protolayout.ModifiersBuilders.Clickable,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.ButtonColors,kotlin.Int,androidx.wear.protolayout.ModifiersBuilders.Padding)( @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/material3/MaterialScope receiver, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/ModifiersBuilders.Clickable onClick, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/modifiers/LayoutModifier modifier, Function1<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/material3/MaterialScope, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement> labelContent, Function1<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/material3/MaterialScope, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement> iconContent, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/DimensionBuilders.ContainerDimension width, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/ModifiersBuilders.Corner shape, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/material3/ButtonColors colors, int horizontalAlignment, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/ModifiersBuilders.Padding contentPadding )` Opinionated ProtoLayout Material3 compact button that offers up to two slots to take horizontally stacked content representing an icon and text next to it. |
| `static final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement` | `https://developer.android.com/reference/androidx/wear/protolayout/material3/ButtonKt#(androidx.wear.protolayout.material3.MaterialScope).iconButton(androidx.wear.protolayout.ModifiersBuilders.Clickable,kotlin.Function1,androidx.wear.protolayout.modifiers.LayoutModifier,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.ButtonColors,androidx.wear.protolayout.material3.IconButtonStyle,androidx.wear.protolayout.ModifiersBuilders.Padding)( @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/material3/MaterialScope receiver, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/ModifiersBuilders.Clickable onClick, @https://developer.android.com/reference/androidx/annotation/NonNull Function1<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/material3/MaterialScope, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement> iconContent, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/modifiers/LayoutModifier modifier, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/DimensionBuilders.ContainerDimension width, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/DimensionBuilders.ContainerDimension height, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/ModifiersBuilders.Corner shape, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/material3/ButtonColors colors, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/material3/IconButtonStyle style, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/ModifiersBuilders.Padding contentPadding )` Opinionated ProtoLayout Material3 icon button that offers a single slot to take content representing icon, for example `https://developer.android.com/reference/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).icon(androidx.wear.protolayout.ResourceBuilders.ImageResource,kotlin.String,androidx.wear.protolayout.DimensionBuilders.ImageDimension,androidx.wear.protolayout.DimensionBuilders.ImageDimension,androidx.wear.protolayout.types.LayoutColor)`. |
| `static final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement` | `https://developer.android.com/reference/androidx/wear/protolayout/material3/ButtonKt#(androidx.wear.protolayout.material3.MaterialScope).imageButton(androidx.wear.protolayout.ModifiersBuilders.Clickable,kotlin.Function1,androidx.wear.protolayout.modifiers.LayoutModifier,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.DimensionBuilders.ContainerDimension)( @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/material3/MaterialScope receiver, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/ModifiersBuilders.Clickable onClick, @https://developer.android.com/reference/androidx/annotation/NonNull Function1<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/material3/MaterialScope, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement> backgroundContent, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/modifiers/LayoutModifier modifier, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/DimensionBuilders.ContainerDimension width, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/DimensionBuilders.ContainerDimension height )` ProtoLayout Material3 clickable image button that doesn't offer additional slots, only image (for example `https://developer.android.com/reference/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).backgroundImage(androidx.wear.protolayout.ResourceBuilders.ImageResource,kotlin.String,androidx.wear.protolayout.modifiers.LayoutModifier,androidx.wear.protolayout.DimensionBuilders.ImageDimension,androidx.wear.protolayout.DimensionBuilders.ImageDimension,androidx.wear.protolayout.types.LayoutColor,kotlin.Int)` as a background). |
| `static final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement` | `https://developer.android.com/reference/androidx/wear/protolayout/material3/ButtonKt#(androidx.wear.protolayout.material3.MaterialScope).textButton(androidx.wear.protolayout.ModifiersBuilders.Clickable,kotlin.Function1,androidx.wear.protolayout.modifiers.LayoutModifier,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.ButtonColors,androidx.wear.protolayout.material3.TextButtonStyle,androidx.wear.protolayout.ModifiersBuilders.Padding)( @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/material3/MaterialScope receiver, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/ModifiersBuilders.Clickable onClick, @https://developer.android.com/reference/androidx/annotation/NonNull Function1<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/material3/MaterialScope, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement> labelContent, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/modifiers/LayoutModifier modifier, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/DimensionBuilders.ContainerDimension width, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/DimensionBuilders.ContainerDimension height, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/ModifiersBuilders.Corner shape, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/material3/ButtonColors colors, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/material3/TextButtonStyle style, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/ModifiersBuilders.Padding contentPadding )` Opinionated ProtoLayout Material3 text button that offers a single slot to take content representing short text, for example `https://developer.android.com/reference/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).text(androidx.wear.protolayout.types.LayoutString,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Int,androidx.wear.protolayout.types.LayoutColor,kotlin.Boolean,kotlin.Boolean,kotlin.Boolean,kotlin.Int,kotlin.Int,kotlin.Int,kotlin.collections.List,kotlin.collections.List)`. |
## Public methods
### avatarButton
Artifact: [androidx.wear.protolayout:protolayout-material3](https://developer.android.com/jetpack/androidx/releases/wear-protolayout) [View Source](https://cs.android.com/search?q=file:androidx/wear/protolayout/material3/Button.kt+function:avatarButton)
```
public static final @NonNull LayoutElementBuilders.LayoutElement avatarButton(
@NonNull MaterialScope receiver,
@NonNull ModifiersBuilders.Clickable onClick,
@NonNull Function1<@NonNull MaterialScope, @NonNull LayoutElementBuilders.LayoutElement> labelContent,
@NonNull Function1<@NonNull MaterialScope, @NonNull LayoutElementBuilders.LayoutElement> avatarContent,
@NonNull LayoutModifier modifier,
Function1<@NonNull MaterialScope, @NonNull LayoutElementBuilders.LayoutElement> secondaryLabelContent,
@NonNull DimensionBuilders.ContainerDimension height,
@NonNull ModifiersBuilders.Corner shape,
@NonNull ButtonColors colors,
@NonNull AvatarButtonStyle style,
int horizontalAlignment,
@NonNull ModifiersBuilders.Padding contentPadding
)
```
Opinionated ProtoLayout Material3 pill shape avatar button that offers up to three slots to take content representing vertically stacked label and secondary label, and an image (avatar) next to it.
Difference from the `https://developer.android.com/reference/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).button(androidx.wear.protolayout.ModifiersBuilders.Clickable,kotlin.Function1,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.ButtonColors,kotlin.Function1,androidx.wear.protolayout.material3.ButtonStyle,kotlin.Int,androidx.wear.protolayout.ModifiersBuilders.Padding)` is that this one takes an image instead of an icon and spaces the content proportionally, so that edge of the button nicely hugs the avatar image.
The button's `https://developer.android.com/reference/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).avatarButton(androidx.wear.protolayout.ModifiersBuilders.Clickable,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Function1,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.ButtonColors,androidx.wear.protolayout.material3.AvatarButtonStyle,kotlin.Int,androidx.wear.protolayout.ModifiersBuilders.Padding)` default to using `https://developer.android.com/reference/androidx/wear/protolayout/material3/ColorScheme` from the `https://developer.android.com/reference/androidx/wear/protolayout/material3/MaterialScope` it's defined in, which defaults to `https://developer.android.com/reference/androidx/wear/protolayout/material3/package-summary#dynamicColorScheme(android.content.Context,androidx.wear.protolayout.material3.ColorScheme)`, meaning that the colors follow system theme if available on device. If not, or switched off by user, uses fallback `https://developer.android.com/reference/androidx/wear/protolayout/material3/ColorScheme` defined in its `https://developer.android.com/reference/androidx/wear/protolayout/material3/MaterialScope`.
See [common-layouts/tiles](https://developer.android.com/design/ui/wear/guides/foundations/common-layouts/tiles) and [bestpractices](https://developer.android.com/design/ui/wear/guides/surfaces/tiles/bestpractices) for more visuals and design recommendations.
```kotlin
import androidx.wear.protolayout.material3.avatarButton
import androidx.wear.protolayout.material3.avatarImage
import androidx.wear.protolayout.material3.button
import androidx.wear.protolayout.material3.text
import androidx.wear.protolayout.modifiers.LayoutModifier
import androidx.wear.protolayout.modifiers.clickable
import androidx.wear.protolayout.modifiers.contentDescription
import androidx.wear.protolayout.types.layoutString
avatarButton(
onClick = clickable(),
modifier = LayoutModifier.contentDescription("Pill button"),
avatarContent = { avatarImage("id") },
labelContent = { text("Primary label".layoutString) },
secondaryLabelContent = { text("Secondary label".layoutString) },
)
```
| Parameters |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/ModifiersBuilders.Clickable onClick` | Associated `https://developer.android.com/reference/androidx/wear/protolayout/ModifiersBuilders.Clickable` for click events. When the button is clicked it will fire the associated action. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull Function1<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/material3/MaterialScope, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement> labelContent` | The text slot for content displayed in this button. It is recommended to use default styling that is automatically provided by only calling `https://developer.android.com/reference/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).text(androidx.wear.protolayout.types.LayoutString,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Int,androidx.wear.protolayout.types.LayoutColor,kotlin.Boolean,kotlin.Boolean,kotlin.Boolean,kotlin.Int,kotlin.Int,kotlin.Int,kotlin.collections.List,kotlin.collections.List)`. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull Function1<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/material3/MaterialScope, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement> avatarContent` | The avatar slot for content displayed in this button. It is recommended to use default styling that is automatically provided by only calling `https://developer.android.com/reference/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).avatarImage(androidx.wear.protolayout.ResourceBuilders.ImageResource,kotlin.String,androidx.wear.protolayout.DimensionBuilders.ImageDimension,androidx.wear.protolayout.DimensionBuilders.ImageDimension,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Int)` with the resource ID. Width and height of this element should be set to `https://developer.android.com/reference/androidx/wear/protolayout/DimensionBuilders#expand()`. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/modifiers/LayoutModifier modifier` | Modifiers to set to this element. It's highly recommended to set a content description using `https://developer.android.com/reference/androidx/wear/protolayout/modifiers/package-summary#(androidx.wear.protolayout.modifiers.LayoutModifier).contentDescription(kotlin.String,androidx.wear.protolayout.expression.DynamicBuilders.DynamicString)`. |
| `Function1<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/material3/MaterialScope, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement> secondaryLabelContent` | The text slot for content displayed in this button. It is recommended to use default styling that is automatically provided by only calling `https://developer.android.com/reference/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).text(androidx.wear.protolayout.types.LayoutString,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Int,androidx.wear.protolayout.types.LayoutColor,kotlin.Boolean,kotlin.Boolean,kotlin.Boolean,kotlin.Int,kotlin.Int,kotlin.Int,kotlin.collections.List,kotlin.collections.List)`. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/DimensionBuilders.ContainerDimension height` | The height of this button. It's highly recommended to set this to `https://developer.android.com/reference/androidx/wear/protolayout/DimensionBuilders#expand()` or `https://developer.android.com/reference/androidx/wear/protolayout/DimensionBuilders#weight(float)` |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/ModifiersBuilders.Corner shape` | Defines the button's shape, in other words the corner radius for this button. If changing these to radius smaller than `https://developer.android.com/reference/androidx/wear/protolayout/material3/Shapes#medium()`, it is important to adjusts the margins of `https://developer.android.com/reference/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).primaryLayout(kotlin.Function1,kotlin.Function1,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.ModifiersBuilders.Clickable,androidx.wear.protolayout.material3.PrimaryLayoutMargins)` used to accommodate for more space, for example by using `https://developer.android.com/reference/androidx/wear/protolayout/material3/PredefinedPrimaryLayoutMargins#(androidx.wear.protolayout.material3.MaterialScope).maxPrimaryLayoutMargins()`. Or, if the `https://developer.android.com/reference/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).avatarButton(androidx.wear.protolayout.ModifiersBuilders.Clickable,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Function1,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.ButtonColors,androidx.wear.protolayout.material3.AvatarButtonStyle,kotlin.Int,androidx.wear.protolayout.ModifiersBuilders.Padding)` is set to `https://developer.android.com/reference/androidx/wear/protolayout/material3/Shapes#full()`, using `https://developer.android.com/reference/androidx/wear/protolayout/material3/PredefinedPrimaryLayoutMargins#(androidx.wear.protolayout.material3.MaterialScope).minPrimaryLayoutMargins()` can be considered. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/material3/ButtonColors colors` | The colors used for this button. If not set, `https://developer.android.com/reference/androidx/wear/protolayout/material3/ButtonDefaults#(androidx.wear.protolayout.material3.MaterialScope).filledButtonColors()` will be used as high emphasis button. Other recommended colors are `https://developer.android.com/reference/androidx/wear/protolayout/material3/ButtonDefaults#(androidx.wear.protolayout.material3.MaterialScope).filledTonalButtonColors()` and `https://developer.android.com/reference/androidx/wear/protolayout/material3/ButtonDefaults#(androidx.wear.protolayout.material3.MaterialScope).filledVariantButtonColors()`. If using custom colors, it is important to choose a color pair from same role to ensure accessibility with sufficient color contrast. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/material3/AvatarButtonStyle style` | The style which provides the attribute values required for constructing this pill shape button and its inner content. It also provides default style for the inner content, that can be overridden by each content slot. |
| `int horizontalAlignment` | The horizontal placement of the `https://developer.android.com/reference/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).avatarButton(androidx.wear.protolayout.ModifiersBuilders.Clickable,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Function1,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.ButtonColors,androidx.wear.protolayout.material3.AvatarButtonStyle,kotlin.Int,androidx.wear.protolayout.ModifiersBuilders.Padding)`. This should be `https://developer.android.com/reference/androidx/wear/protolayout/LayoutElementBuilders#HORIZONTAL_ALIGN_START()` to place the `https://developer.android.com/reference/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).avatarButton(androidx.wear.protolayout.ModifiersBuilders.Clickable,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Function1,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.ButtonColors,androidx.wear.protolayout.material3.AvatarButtonStyle,kotlin.Int,androidx.wear.protolayout.ModifiersBuilders.Padding)` on the start side of the button, or `https://developer.android.com/reference/androidx/wear/protolayout/LayoutElementBuilders#HORIZONTAL_ALIGN_END()` to place in on the end side. `https://developer.android.com/reference/androidx/wear/protolayout/LayoutElementBuilders#HORIZONTAL_ALIGN_CENTER()` will be ignored and replaced with `https://developer.android.com/reference/androidx/wear/protolayout/LayoutElementBuilders#HORIZONTAL_ALIGN_START()`. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/ModifiersBuilders.Padding contentPadding` | The inner padding used to prevent inner content from being too close to the button's edge. It's highly recommended to keep the default. Only vertical values would be used, as horizontally elements are spaced out proportionally to the buttons width. |
### button
Artifact: [androidx.wear.protolayout:protolayout-material3](https://developer.android.com/jetpack/androidx/releases/wear-protolayout) [View Source](https://cs.android.com/search?q=file:androidx/wear/protolayout/material3/Button.kt+function:button)
```
public static final @NonNull LayoutElementBuilders.LayoutElement button(
@NonNull MaterialScope receiver,
@NonNull ModifiersBuilders.Clickable onClick,
@NonNull Function1<@NonNull MaterialScope, @NonNull LayoutElementBuilders.LayoutElement> labelContent,
@NonNull LayoutModifier modifier,
Function1<@NonNull MaterialScope, @NonNull LayoutElementBuilders.LayoutElement> secondaryLabelContent,
Function1<@NonNull MaterialScope, @NonNull LayoutElementBuilders.LayoutElement> iconContent,
@NonNull DimensionBuilders.ContainerDimension width,
@NonNull DimensionBuilders.ContainerDimension height,
@NonNull ModifiersBuilders.Corner shape,
@NonNull ButtonColors colors,
Function1<@NonNull MaterialScope, @NonNull LayoutElementBuilders.LayoutElement> backgroundContent,
@NonNull ButtonStyle style,
int horizontalAlignment,
@NonNull ModifiersBuilders.Padding contentPadding
)
```
Opinionated ProtoLayout Material3 pill shape button that offers up to three slots to take content representing vertically stacked label and secondary label, and an icon next to it.
The button's `https://developer.android.com/reference/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).button(androidx.wear.protolayout.ModifiersBuilders.Clickable,kotlin.Function1,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.ButtonColors,kotlin.Function1,androidx.wear.protolayout.material3.ButtonStyle,kotlin.Int,androidx.wear.protolayout.ModifiersBuilders.Padding)` default to using `https://developer.android.com/reference/androidx/wear/protolayout/material3/ColorScheme` from the `https://developer.android.com/reference/androidx/wear/protolayout/material3/MaterialScope` it's defined in, which defaults to `https://developer.android.com/reference/androidx/wear/protolayout/material3/package-summary#dynamicColorScheme(android.content.Context,androidx.wear.protolayout.material3.ColorScheme)`, meaning that the colors follow system theme if available on device. If not, or switched off by user, uses fallback `https://developer.android.com/reference/androidx/wear/protolayout/material3/ColorScheme` defined in its `https://developer.android.com/reference/androidx/wear/protolayout/material3/MaterialScope`.
See [common-layouts/tiles](https://developer.android.com/design/ui/wear/guides/foundations/common-layouts/tiles) and [bestpractices](https://developer.android.com/design/ui/wear/guides/surfaces/tiles/bestpractices) for more visuals and design recommendations.
```kotlin
import androidx.wear.protolayout.DimensionBuilders.expand
import androidx.wear.protolayout.material3.button
import androidx.wear.protolayout.material3.icon
import androidx.wear.protolayout.material3.materialScope
import androidx.wear.protolayout.material3.primaryLayout
import androidx.wear.protolayout.material3.text
import androidx.wear.protolayout.modifiers.LayoutModifier
import androidx.wear.protolayout.modifiers.clickable
import androidx.wear.protolayout.modifiers.contentDescription
import androidx.wear.protolayout.types.layoutString
materialScope(context, deviceConfiguration) {
primaryLayout(
mainSlot = {
button(
onClick = clickable,
modifier = LayoutModifier.contentDescription("Pill shape button"),
width = expand(),
height = expand(),
labelContent = { text("First label".layoutString) },
secondaryLabelContent = { text("Second label".layoutString) },
iconContent = { icon("id") },
)
}
)
}
```
```kotlin
import androidx.wear.protolayout.DimensionBuilders.expand
import androidx.wear.protolayout.LayoutElementBuilders.Box
import androidx.wear.protolayout.material3.button
import androidx.wear.protolayout.material3.materialScope
import androidx.wear.protolayout.material3.primaryLayout
import androidx.wear.protolayout.material3.text
import androidx.wear.protolayout.modifiers.LayoutModifier
import androidx.wear.protolayout.modifiers.background
import androidx.wear.protolayout.modifiers.clickable
import androidx.wear.protolayout.modifiers.contentDescription
materialScope(context, deviceConfiguration) {
primaryLayout(
mainSlot = {
// Button with custom content inside
button(
onClick = clickable,
modifier =
LayoutModifier.contentDescription("Big button with image background")
.background(colorScheme.primary),
width = expand(),
height = expand(),
labelContent = {
// This can be further built.
Box.Builder().build()
},
)
}
)
}
```
| Parameters |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/ModifiersBuilders.Clickable onClick` | Associated `https://developer.android.com/reference/androidx/wear/protolayout/ModifiersBuilders.Clickable` for click events. When the button is clicked it will fire the associated action. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull Function1<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/material3/MaterialScope, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement> labelContent` | The text slot for content displayed in this button. It is recommended to use default styling that is automatically provided by only calling `https://developer.android.com/reference/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).text(androidx.wear.protolayout.types.LayoutString,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Int,androidx.wear.protolayout.types.LayoutColor,kotlin.Boolean,kotlin.Boolean,kotlin.Boolean,kotlin.Int,kotlin.Int,kotlin.Int,kotlin.collections.List,kotlin.collections.List)`. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/modifiers/LayoutModifier modifier` | Modifiers to set to this element. It's highly recommended to set a content description using `https://developer.android.com/reference/androidx/wear/protolayout/modifiers/package-summary#(androidx.wear.protolayout.modifiers.LayoutModifier).contentDescription(kotlin.String,androidx.wear.protolayout.expression.DynamicBuilders.DynamicString)`. |
| `Function1<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/material3/MaterialScope, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement> secondaryLabelContent` | The text slot for content displayed in this button. It is recommended to use default styling that is automatically provided by only calling `https://developer.android.com/reference/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).text(androidx.wear.protolayout.types.LayoutString,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Int,androidx.wear.protolayout.types.LayoutColor,kotlin.Boolean,kotlin.Boolean,kotlin.Boolean,kotlin.Int,kotlin.Int,kotlin.Int,kotlin.collections.List,kotlin.collections.List)`. |
| `Function1<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/material3/MaterialScope, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement> iconContent` | The icon slot for content displayed in this button. It is recommended to use default styling that is automatically provided by only calling `https://developer.android.com/reference/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).icon(androidx.wear.protolayout.ResourceBuilders.ImageResource,kotlin.String,androidx.wear.protolayout.DimensionBuilders.ImageDimension,androidx.wear.protolayout.DimensionBuilders.ImageDimension,androidx.wear.protolayout.types.LayoutColor)` with the resource ID. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/DimensionBuilders.ContainerDimension width` | The width of this button. It's highly recommended to set this to `https://developer.android.com/reference/androidx/wear/protolayout/DimensionBuilders#expand()` or `https://developer.android.com/reference/androidx/wear/protolayout/DimensionBuilders#weight(float)` |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/DimensionBuilders.ContainerDimension height` | The height of this button. It's highly recommended to set this to `https://developer.android.com/reference/androidx/wear/protolayout/DimensionBuilders#expand()` or `https://developer.android.com/reference/androidx/wear/protolayout/DimensionBuilders#weight(float)` |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/ModifiersBuilders.Corner shape` | Defines the button's shape, in other words the corner radius for this button. If changing these to radius smaller than `https://developer.android.com/reference/androidx/wear/protolayout/material3/Shapes#medium()`, it is important to adjusts the margins of `https://developer.android.com/reference/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).primaryLayout(kotlin.Function1,kotlin.Function1,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.ModifiersBuilders.Clickable,androidx.wear.protolayout.material3.PrimaryLayoutMargins)` used to accommodate for more space, for example by using `https://developer.android.com/reference/androidx/wear/protolayout/material3/PredefinedPrimaryLayoutMargins#(androidx.wear.protolayout.material3.MaterialScope).maxPrimaryLayoutMargins()`. Or, if the `https://developer.android.com/reference/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).button(androidx.wear.protolayout.ModifiersBuilders.Clickable,kotlin.Function1,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.ButtonColors,kotlin.Function1,androidx.wear.protolayout.material3.ButtonStyle,kotlin.Int,androidx.wear.protolayout.ModifiersBuilders.Padding)` is set to `https://developer.android.com/reference/androidx/wear/protolayout/material3/Shapes#full()`, using `https://developer.android.com/reference/androidx/wear/protolayout/material3/PredefinedPrimaryLayoutMargins#(androidx.wear.protolayout.material3.MaterialScope).minPrimaryLayoutMargins()` can be considered. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/material3/ButtonColors colors` | The colors used for this button. If not set, `https://developer.android.com/reference/androidx/wear/protolayout/material3/ButtonDefaults#(androidx.wear.protolayout.material3.MaterialScope).filledButtonColors()` will be used as high emphasis button. Other recommended colors are `https://developer.android.com/reference/androidx/wear/protolayout/material3/ButtonDefaults#(androidx.wear.protolayout.material3.MaterialScope).filledTonalButtonColors()` and `https://developer.android.com/reference/androidx/wear/protolayout/material3/ButtonDefaults#(androidx.wear.protolayout.material3.MaterialScope).filledVariantButtonColors()`. If using custom colors, it is important to choose a color pair from same role to ensure accessibility with sufficient color contrast. |
| `Function1<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/material3/MaterialScope, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement> backgroundContent` | The background object to be used behind the content in the button. It is recommended to use the default styling that is automatically provided by only calling `https://developer.android.com/reference/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).backgroundImage(androidx.wear.protolayout.ResourceBuilders.ImageResource,kotlin.String,androidx.wear.protolayout.modifiers.LayoutModifier,androidx.wear.protolayout.DimensionBuilders.ImageDimension,androidx.wear.protolayout.DimensionBuilders.ImageDimension,androidx.wear.protolayout.types.LayoutColor,kotlin.Int)` with the content. It can be combined with the specified `https://developer.android.com/reference/androidx/wear/protolayout/material3/ButtonColors#containerColor()` behind it. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/material3/ButtonStyle style` | The style which provides the attribute values required for constructing this pill shape button and its inner content. It also provides default style for the inner content, that can be overridden by each content slot. |
| `int horizontalAlignment` | The horizontal placement of the `https://developer.android.com/reference/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).button(androidx.wear.protolayout.ModifiersBuilders.Clickable,kotlin.Function1,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.ButtonColors,kotlin.Function1,androidx.wear.protolayout.material3.ButtonStyle,kotlin.Int,androidx.wear.protolayout.ModifiersBuilders.Padding)` and `https://developer.android.com/reference/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).button(androidx.wear.protolayout.ModifiersBuilders.Clickable,kotlin.Function1,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.ButtonColors,kotlin.Function1,androidx.wear.protolayout.material3.ButtonStyle,kotlin.Int,androidx.wear.protolayout.ModifiersBuilders.Padding)` content. If `https://developer.android.com/reference/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).button(androidx.wear.protolayout.ModifiersBuilders.Clickable,kotlin.Function1,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.ButtonColors,kotlin.Function1,androidx.wear.protolayout.material3.ButtonStyle,kotlin.Int,androidx.wear.protolayout.ModifiersBuilders.Padding)` is present, this should be `https://developer.android.com/reference/androidx/wear/protolayout/LayoutElementBuilders#HORIZONTAL_ALIGN_START()`. Defaults to `https://developer.android.com/reference/androidx/wear/protolayout/LayoutElementBuilders#HORIZONTAL_ALIGN_CENTER()` if only `https://developer.android.com/reference/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).button(androidx.wear.protolayout.ModifiersBuilders.Clickable,kotlin.Function1,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.ButtonColors,kotlin.Function1,androidx.wear.protolayout.material3.ButtonStyle,kotlin.Int,androidx.wear.protolayout.ModifiersBuilders.Padding)` is present, otherwise it default to `https://developer.android.com/reference/androidx/wear/protolayout/LayoutElementBuilders#HORIZONTAL_ALIGN_START()`. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/ModifiersBuilders.Padding contentPadding` | The inner padding used to prevent inner content from being too close to the button's edge. It's highly recommended to keep the default. |
### compactButton
Artifact: [androidx.wear.protolayout:protolayout-material3](https://developer.android.com/jetpack/androidx/releases/wear-protolayout) [View Source](https://cs.android.com/search?q=file:androidx/wear/protolayout/material3/Button.kt+function:compactButton)
```
public static final @NonNull LayoutElementBuilders.LayoutElement compactButton(
@NonNull MaterialScope receiver,
@NonNull ModifiersBuilders.Clickable onClick,
@NonNull LayoutModifier modifier,
Function1<@NonNull MaterialScope, @NonNull LayoutElementBuilders.LayoutElement> labelContent,
Function1<@NonNull MaterialScope, @NonNull LayoutElementBuilders.LayoutElement> iconContent,
@NonNull DimensionBuilders.ContainerDimension width,
@NonNull ModifiersBuilders.Corner shape,
@NonNull ButtonColors colors,
int horizontalAlignment,
@NonNull ModifiersBuilders.Padding contentPadding
)
```
Opinionated ProtoLayout Material3 compact button that offers up to two slots to take horizontally stacked content representing an icon and text next to it.
The button's `https://developer.android.com/reference/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).compactButton(androidx.wear.protolayout.ModifiersBuilders.Clickable,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.ButtonColors,kotlin.Int,androidx.wear.protolayout.ModifiersBuilders.Padding)` default to using `https://developer.android.com/reference/androidx/wear/protolayout/material3/ColorScheme` from the `https://developer.android.com/reference/androidx/wear/protolayout/material3/MaterialScope` it's defined in, which defaults to `https://developer.android.com/reference/androidx/wear/protolayout/material3/package-summary#dynamicColorScheme(android.content.Context,androidx.wear.protolayout.material3.ColorScheme)`, meaning that the colors follow system theme if available on device. If not, or switched off by user, uses fallback `https://developer.android.com/reference/androidx/wear/protolayout/material3/ColorScheme` defined in its `https://developer.android.com/reference/androidx/wear/protolayout/material3/MaterialScope`.
See [common-layouts/tiles](https://developer.android.com/design/ui/wear/guides/foundations/common-layouts/tiles) and [bestpractices](https://developer.android.com/design/ui/wear/guides/surfaces/tiles/bestpractices) for more visuals and design recommendations.
```kotlin
import androidx.wear.protolayout.DimensionBuilders.expand
import androidx.wear.protolayout.material3.button
import androidx.wear.protolayout.material3.compactButton
import androidx.wear.protolayout.material3.icon
import androidx.wear.protolayout.material3.materialScope
import androidx.wear.protolayout.material3.primaryLayout
import androidx.wear.protolayout.material3.text
import androidx.wear.protolayout.modifiers.LayoutModifier
import androidx.wear.protolayout.modifiers.clickable
import androidx.wear.protolayout.modifiers.contentDescription
import androidx.wear.protolayout.types.layoutString
materialScope(context, deviceConfiguration) {
primaryLayout(
mainSlot = {
compactButton(
onClick = clickable,
modifier = LayoutModifier.contentDescription("Compact button"),
width = expand(),
labelContent = { text("Action".layoutString) },
iconContent = { icon("id") },
)
}
)
}
```
| Parameters |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/ModifiersBuilders.Clickable onClick` | Associated `https://developer.android.com/reference/androidx/wear/protolayout/ModifiersBuilders.Clickable` for click events. When the button is clicked it will fire the associated action. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/modifiers/LayoutModifier modifier` | Modifiers to set to this element. It's highly recommended to set a content description using `https://developer.android.com/reference/androidx/wear/protolayout/modifiers/package-summary#(androidx.wear.protolayout.modifiers.LayoutModifier).contentDescription(kotlin.String,androidx.wear.protolayout.expression.DynamicBuilders.DynamicString)`. |
| `Function1<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/material3/MaterialScope, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement> labelContent` | The text slot for content displayed in this button. It is recommended to use default styling that is automatically provided by calling `https://developer.android.com/reference/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).text(androidx.wear.protolayout.types.LayoutString,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Int,androidx.wear.protolayout.types.LayoutColor,kotlin.Boolean,kotlin.Boolean,kotlin.Boolean,kotlin.Int,kotlin.Int,kotlin.Int,kotlin.collections.List,kotlin.collections.List)` with only the text data parameter. |
| `Function1<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/material3/MaterialScope, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement> iconContent` | The icon slot for content displayed in this button. It is recommended to use default styling that is automatically provided by only calling `https://developer.android.com/reference/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).icon(androidx.wear.protolayout.ResourceBuilders.ImageResource,kotlin.String,androidx.wear.protolayout.DimensionBuilders.ImageDimension,androidx.wear.protolayout.DimensionBuilders.ImageDimension,androidx.wear.protolayout.types.LayoutColor)` with the resource ID. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/DimensionBuilders.ContainerDimension width` | The width of this button. It's highly recommended to set this to `https://developer.android.com/reference/androidx/wear/protolayout/DimensionBuilders#expand()` or `https://developer.android.com/reference/androidx/wear/protolayout/DimensionBuilders#weight(float)` |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/ModifiersBuilders.Corner shape` | Defines the button's shape, in other words the corner radius for this button. If changing these to radius smaller than `https://developer.android.com/reference/androidx/wear/protolayout/material3/Shapes#medium()`, it is important to adjusts the margins of `https://developer.android.com/reference/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).primaryLayout(kotlin.Function1,kotlin.Function1,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.ModifiersBuilders.Clickable,androidx.wear.protolayout.material3.PrimaryLayoutMargins)` used to accommodate for more space, for example by using `https://developer.android.com/reference/androidx/wear/protolayout/material3/PredefinedPrimaryLayoutMargins#(androidx.wear.protolayout.material3.MaterialScope).maxPrimaryLayoutMargins()`. Or, if the `https://developer.android.com/reference/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).compactButton(androidx.wear.protolayout.ModifiersBuilders.Clickable,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.ButtonColors,kotlin.Int,androidx.wear.protolayout.ModifiersBuilders.Padding)` is set to `https://developer.android.com/reference/androidx/wear/protolayout/material3/Shapes#full()`, using `https://developer.android.com/reference/androidx/wear/protolayout/material3/PredefinedPrimaryLayoutMargins#(androidx.wear.protolayout.material3.MaterialScope).minPrimaryLayoutMargins()` can be considered. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/material3/ButtonColors colors` | The colors used for this button. If not set, `https://developer.android.com/reference/androidx/wear/protolayout/material3/ButtonDefaults#(androidx.wear.protolayout.material3.MaterialScope).filledButtonColors()` will be used as high emphasis button. Other recommended colors are `https://developer.android.com/reference/androidx/wear/protolayout/material3/ButtonDefaults#(androidx.wear.protolayout.material3.MaterialScope).filledTonalButtonColors()` and `https://developer.android.com/reference/androidx/wear/protolayout/material3/ButtonDefaults#(androidx.wear.protolayout.material3.MaterialScope).filledVariantButtonColors()`. If using custom colors, it is important to choose colors from the same role to ensure accessibility with sufficient color contrast. |
| `int horizontalAlignment` | The horizontal placement of the `https://developer.android.com/reference/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).compactButton(androidx.wear.protolayout.ModifiersBuilders.Clickable,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.ButtonColors,kotlin.Int,androidx.wear.protolayout.ModifiersBuilders.Padding)` and `https://developer.android.com/reference/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).compactButton(androidx.wear.protolayout.ModifiersBuilders.Clickable,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.ButtonColors,kotlin.Int,androidx.wear.protolayout.ModifiersBuilders.Padding)` content. If both are present, this should be `https://developer.android.com/reference/androidx/wear/protolayout/LayoutElementBuilders#HORIZONTAL_ALIGN_START()` or `https://developer.android.com/reference/androidx/wear/protolayout/LayoutElementBuilders#HORIZONTAL_ALIGN_END()` (in which case `https://developer.android.com/reference/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).compactButton(androidx.wear.protolayout.ModifiersBuilders.Clickable,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.ButtonColors,kotlin.Int,androidx.wear.protolayout.ModifiersBuilders.Padding)` would be on the start or end side, respectively). Defaults to `https://developer.android.com/reference/androidx/wear/protolayout/LayoutElementBuilders#HORIZONTAL_ALIGN_CENTER()` if only `https://developer.android.com/reference/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).compactButton(androidx.wear.protolayout.ModifiersBuilders.Clickable,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.ButtonColors,kotlin.Int,androidx.wear.protolayout.ModifiersBuilders.Padding)` or `https://developer.android.com/reference/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).compactButton(androidx.wear.protolayout.ModifiersBuilders.Clickable,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.ButtonColors,kotlin.Int,androidx.wear.protolayout.ModifiersBuilders.Padding)` is present, otherwise it default to `https://developer.android.com/reference/androidx/wear/protolayout/LayoutElementBuilders#HORIZONTAL_ALIGN_START()`. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/ModifiersBuilders.Padding contentPadding` | The inner padding used to prevent inner content from being too close to the button's edge. It's highly recommended to keep the default. |
### iconButton
Artifact: [androidx.wear.protolayout:protolayout-material3](https://developer.android.com/jetpack/androidx/releases/wear-protolayout) [View Source](https://cs.android.com/search?q=file:androidx/wear/protolayout/material3/Button.kt+function:iconButton)
```
public static final @NonNull LayoutElementBuilders.LayoutElement iconButton(
@NonNull MaterialScope receiver,
@NonNull ModifiersBuilders.Clickable onClick,
@NonNull Function1<@NonNull MaterialScope, @NonNull LayoutElementBuilders.LayoutElement> iconContent,
@NonNull LayoutModifier modifier,
@NonNull DimensionBuilders.ContainerDimension width,
@NonNull DimensionBuilders.ContainerDimension height,
@NonNull ModifiersBuilders.Corner shape,
@NonNull ButtonColors colors,
@NonNull IconButtonStyle style,
@NonNull ModifiersBuilders.Padding contentPadding
)
```
Opinionated ProtoLayout Material3 icon button that offers a single slot to take content representing icon, for example `https://developer.android.com/reference/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).icon(androidx.wear.protolayout.ResourceBuilders.ImageResource,kotlin.String,androidx.wear.protolayout.DimensionBuilders.ImageDimension,androidx.wear.protolayout.DimensionBuilders.ImageDimension,androidx.wear.protolayout.types.LayoutColor)`.
The button is usually either a circular shape with the same `https://developer.android.com/reference/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).iconButton(androidx.wear.protolayout.ModifiersBuilders.Clickable,kotlin.Function1,androidx.wear.protolayout.modifiers.LayoutModifier,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.ButtonColors,androidx.wear.protolayout.material3.IconButtonStyle,androidx.wear.protolayout.ModifiersBuilders.Padding)` and `https://developer.android.com/reference/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).iconButton(androidx.wear.protolayout.ModifiersBuilders.Clickable,kotlin.Function1,androidx.wear.protolayout.modifiers.LayoutModifier,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.ButtonColors,androidx.wear.protolayout.material3.IconButtonStyle,androidx.wear.protolayout.ModifiersBuilders.Padding)`, or highly recommended stadium shape occupying available space with `https://developer.android.com/reference/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).iconButton(androidx.wear.protolayout.ModifiersBuilders.Clickable,kotlin.Function1,androidx.wear.protolayout.modifiers.LayoutModifier,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.ButtonColors,androidx.wear.protolayout.material3.IconButtonStyle,androidx.wear.protolayout.ModifiersBuilders.Padding)` and `https://developer.android.com/reference/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).iconButton(androidx.wear.protolayout.ModifiersBuilders.Clickable,kotlin.Function1,androidx.wear.protolayout.modifiers.LayoutModifier,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.ButtonColors,androidx.wear.protolayout.material3.IconButtonStyle,androidx.wear.protolayout.ModifiersBuilders.Padding)` set to `https://developer.android.com/reference/androidx/wear/protolayout/DimensionBuilders#expand()` or `https://developer.android.com/reference/androidx/wear/protolayout/DimensionBuilders#weight(float)`, usually arranged with the `https://developer.android.com/reference/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).buttonGroup(androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,kotlin.Float,kotlin.Function1)`.
The button's `https://developer.android.com/reference/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).iconButton(androidx.wear.protolayout.ModifiersBuilders.Clickable,kotlin.Function1,androidx.wear.protolayout.modifiers.LayoutModifier,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.ButtonColors,androidx.wear.protolayout.material3.IconButtonStyle,androidx.wear.protolayout.ModifiersBuilders.Padding)` default to using `https://developer.android.com/reference/androidx/wear/protolayout/material3/ColorScheme` from the `https://developer.android.com/reference/androidx/wear/protolayout/material3/MaterialScope` it's defined in, which defaults to `https://developer.android.com/reference/androidx/wear/protolayout/material3/package-summary#dynamicColorScheme(android.content.Context,androidx.wear.protolayout.material3.ColorScheme)`, meaning that the colors follow system theme if available on device. If not, or switched off by user, uses fallback `https://developer.android.com/reference/androidx/wear/protolayout/material3/ColorScheme` defined in its `https://developer.android.com/reference/androidx/wear/protolayout/material3/MaterialScope`.
See [common-layouts/tiles](https://developer.android.com/design/ui/wear/guides/foundations/common-layouts/tiles) and [bestpractices](https://developer.android.com/design/ui/wear/guides/surfaces/tiles/bestpractices) for more visuals and design recommendations.
```kotlin
import androidx.wear.protolayout.DimensionBuilders.expand
import androidx.wear.protolayout.material3.button
import androidx.wear.protolayout.material3.buttonGroup
import androidx.wear.protolayout.material3.icon
import androidx.wear.protolayout.material3.iconButton
import androidx.wear.protolayout.material3.materialScope
import androidx.wear.protolayout.material3.primaryLayout
import androidx.wear.protolayout.material3.text
import androidx.wear.protolayout.material3.textButton
import androidx.wear.protolayout.modifiers.LayoutModifier
import androidx.wear.protolayout.modifiers.background
import androidx.wear.protolayout.modifiers.clickable
import androidx.wear.protolayout.modifiers.contentDescription
import androidx.wear.protolayout.types.layoutString
materialScope(context, deviceConfiguration) {
primaryLayout(
mainSlot = {
buttonGroup {
buttonGroupItem {
iconButton(
onClick = clickable,
modifier =
LayoutModifier.contentDescription(
"Big button with image background"
),
width = expand(),
height = expand(),
iconContent = { icon("id1") },
)
}
buttonGroupItem {
iconButton(
onClick = clickable,
modifier =
LayoutModifier.contentDescription(
"Big button with image background"
),
width = expand(),
height = expand(),
shape = shapes.large,
iconContent = { icon("id2") },
)
}
buttonGroupItem {
textButton(
onClick = clickable,
modifier =
LayoutModifier.contentDescription(
"Big button with image background"
),
width = expand(),
height = expand(),
shape = shapes.large,
labelContent = { text("Dec".layoutString) },
)
}
}
}
)
}
```
| Parameters |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/ModifiersBuilders.Clickable onClick` | Associated `https://developer.android.com/reference/androidx/wear/protolayout/ModifiersBuilders.Clickable` for click events. When the button is clicked it will fire the associated action. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull Function1<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/material3/MaterialScope, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement> iconContent` | The icon slot for content displayed in this button. It is recommended to use default styling that is automatically provided by only calling `https://developer.android.com/reference/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).icon(androidx.wear.protolayout.ResourceBuilders.ImageResource,kotlin.String,androidx.wear.protolayout.DimensionBuilders.ImageDimension,androidx.wear.protolayout.DimensionBuilders.ImageDimension,androidx.wear.protolayout.types.LayoutColor)` with the resource ID. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/modifiers/LayoutModifier modifier` | Modifiers to set to this element. It's highly recommended to set a content description using `https://developer.android.com/reference/androidx/wear/protolayout/modifiers/package-summary#(androidx.wear.protolayout.modifiers.LayoutModifier).contentDescription(kotlin.String,androidx.wear.protolayout.expression.DynamicBuilders.DynamicString)`. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/DimensionBuilders.ContainerDimension width` | The width of this button. It's highly recommended to set this to `https://developer.android.com/reference/androidx/wear/protolayout/DimensionBuilders#expand()` or `https://developer.android.com/reference/androidx/wear/protolayout/DimensionBuilders#weight(float)` |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/DimensionBuilders.ContainerDimension height` | The height of this button. It's highly recommended to set this to `https://developer.android.com/reference/androidx/wear/protolayout/DimensionBuilders#expand()` or `https://developer.android.com/reference/androidx/wear/protolayout/DimensionBuilders#weight(float)` |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/ModifiersBuilders.Corner shape` | Defines the button's shape, in other words the corner radius for this button. If changing these to radius smaller than `https://developer.android.com/reference/androidx/wear/protolayout/material3/Shapes#medium()`, it is important to adjusts the margins of `https://developer.android.com/reference/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).primaryLayout(kotlin.Function1,kotlin.Function1,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.ModifiersBuilders.Clickable,androidx.wear.protolayout.material3.PrimaryLayoutMargins)` used to accommodate for more space, for example by using `https://developer.android.com/reference/androidx/wear/protolayout/material3/PredefinedPrimaryLayoutMargins#(androidx.wear.protolayout.material3.MaterialScope).maxPrimaryLayoutMargins()`. Or, if the `https://developer.android.com/reference/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).iconButton(androidx.wear.protolayout.ModifiersBuilders.Clickable,kotlin.Function1,androidx.wear.protolayout.modifiers.LayoutModifier,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.ButtonColors,androidx.wear.protolayout.material3.IconButtonStyle,androidx.wear.protolayout.ModifiersBuilders.Padding)` is set to `https://developer.android.com/reference/androidx/wear/protolayout/material3/Shapes#full()`, using `https://developer.android.com/reference/androidx/wear/protolayout/material3/PredefinedPrimaryLayoutMargins#(androidx.wear.protolayout.material3.MaterialScope).minPrimaryLayoutMargins()` can be considered. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/material3/ButtonColors colors` | The colors used for this button. If not set, `https://developer.android.com/reference/androidx/wear/protolayout/material3/ButtonDefaults#(androidx.wear.protolayout.material3.MaterialScope).filledButtonColors()` will be used as high emphasis button. Other recommended colors are `https://developer.android.com/reference/androidx/wear/protolayout/material3/ButtonDefaults#(androidx.wear.protolayout.material3.MaterialScope).filledTonalButtonColors()` and `https://developer.android.com/reference/androidx/wear/protolayout/material3/ButtonDefaults#(androidx.wear.protolayout.material3.MaterialScope).filledVariantButtonColors()`. If using custom colors, it is important to choose a color pair from same role to ensure accessibility with sufficient color contrast. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/material3/IconButtonStyle style` | The style which provides the attribute values required for constructing this icon button and its inner content. It also provides default style for the inner content, that can be overridden by each content slot. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/ModifiersBuilders.Padding contentPadding` | The inner padding used to prevent inner content from being too close to the button's edge. It's highly recommended to keep the default. |
### imageButton
Artifact: [androidx.wear.protolayout:protolayout-material3](https://developer.android.com/jetpack/androidx/releases/wear-protolayout) [View Source](https://cs.android.com/search?q=file:androidx/wear/protolayout/material3/Button.kt+function:imageButton)
```
public static final @NonNull LayoutElementBuilders.LayoutElement imageButton(
@NonNull MaterialScope receiver,
@NonNull ModifiersBuilders.Clickable onClick,
@NonNull Function1<@NonNull MaterialScope, @NonNull LayoutElementBuilders.LayoutElement> backgroundContent,
@NonNull LayoutModifier modifier,
@NonNull DimensionBuilders.ContainerDimension width,
@NonNull DimensionBuilders.ContainerDimension height
)
```
ProtoLayout Material3 clickable image button that doesn't offer additional slots, only image (for example `https://developer.android.com/reference/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).backgroundImage(androidx.wear.protolayout.ResourceBuilders.ImageResource,kotlin.String,androidx.wear.protolayout.modifiers.LayoutModifier,androidx.wear.protolayout.DimensionBuilders.ImageDimension,androidx.wear.protolayout.DimensionBuilders.ImageDimension,androidx.wear.protolayout.types.LayoutColor,kotlin.Int)` as a background).
The button is usually stadium or circle shaped with fully rounded corners by default. It is highly recommended to set its width and height to fill the available space, by `https://developer.android.com/reference/androidx/wear/protolayout/DimensionBuilders#expand()` or `https://developer.android.com/reference/androidx/wear/protolayout/DimensionBuilders#weight(float)` for optimal experience across different screen sizes, and use `https://developer.android.com/reference/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).buttonGroup(androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,kotlin.Float,kotlin.Function1)` to arrange them.
```kotlin
import androidx.wear.protolayout.DimensionBuilders.expand
import androidx.wear.protolayout.material3.backgroundImage
import androidx.wear.protolayout.material3.button
import androidx.wear.protolayout.material3.imageButton
import androidx.wear.protolayout.material3.materialScope
import androidx.wear.protolayout.material3.primaryLayout
import androidx.wear.protolayout.material3.text
import androidx.wear.protolayout.modifiers.LayoutModifier
import androidx.wear.protolayout.modifiers.background
import androidx.wear.protolayout.modifiers.clickable
import androidx.wear.protolayout.modifiers.contentDescription
materialScope(context, deviceConfiguration) {
primaryLayout(
mainSlot = {
imageButton(
onClick = clickable,
modifier =
LayoutModifier.contentDescription("Big button with image background"),
width = expand(),
height = expand(),
backgroundContent = { backgroundImage(protoLayoutResourceId = "id") },
)
}
)
}
```
| Parameters |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/ModifiersBuilders.Clickable onClick` | Associated `https://developer.android.com/reference/androidx/wear/protolayout/ModifiersBuilders.Clickable` for click events. When the button is clicked it will fire the associated action. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull Function1<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/material3/MaterialScope, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement> backgroundContent` | The background object to be used behind the content in the button. It is recommended to use the default styling that is automatically provided by only calling `https://developer.android.com/reference/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).backgroundImage(androidx.wear.protolayout.ResourceBuilders.ImageResource,kotlin.String,androidx.wear.protolayout.modifiers.LayoutModifier,androidx.wear.protolayout.DimensionBuilders.ImageDimension,androidx.wear.protolayout.DimensionBuilders.ImageDimension,androidx.wear.protolayout.types.LayoutColor,kotlin.Int)` with the content and optional overlay. It can be combined with the specified `https://developer.android.com/reference/androidx/wear/protolayout/modifiers/package-summary#(androidx.wear.protolayout.modifiers.LayoutModifier).background(androidx.wear.protolayout.types.LayoutColor)` behind it. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/modifiers/LayoutModifier modifier` | Modifiers to set to this element. It's highly recommended to set a content description using `https://developer.android.com/reference/androidx/wear/protolayout/modifiers/package-summary#(androidx.wear.protolayout.modifiers.LayoutModifier).contentDescription(kotlin.String,androidx.wear.protolayout.expression.DynamicBuilders.DynamicString)`. If `https://developer.android.com/reference/androidx/wear/protolayout/modifiers/package-summary#(androidx.wear.protolayout.modifiers.LayoutModifier).background(androidx.wear.protolayout.types.LayoutColor)` modifier is used and the the background image is also specified, the image will be laid out on top of this color. In case of the fully opaque background image, then the background color will not be shown. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/DimensionBuilders.ContainerDimension width` | The width of this button. It's highly recommended to set this to `https://developer.android.com/reference/androidx/wear/protolayout/DimensionBuilders#expand()` or `https://developer.android.com/reference/androidx/wear/protolayout/DimensionBuilders#weight(float)` |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/DimensionBuilders.ContainerDimension height` | The height of this button. It's highly recommended to set this to `https://developer.android.com/reference/androidx/wear/protolayout/DimensionBuilders#expand()` or `https://developer.android.com/reference/androidx/wear/protolayout/DimensionBuilders#weight(float)` |
### textButton
Artifact: [androidx.wear.protolayout:protolayout-material3](https://developer.android.com/jetpack/androidx/releases/wear-protolayout) [View Source](https://cs.android.com/search?q=file:androidx/wear/protolayout/material3/Button.kt+function:textButton)
```
public static final @NonNull LayoutElementBuilders.LayoutElement textButton(
@NonNull MaterialScope receiver,
@NonNull ModifiersBuilders.Clickable onClick,
@NonNull Function1<@NonNull MaterialScope, @NonNull LayoutElementBuilders.LayoutElement> labelContent,
@NonNull LayoutModifier modifier,
@NonNull DimensionBuilders.ContainerDimension width,
@NonNull DimensionBuilders.ContainerDimension height,
@NonNull ModifiersBuilders.Corner shape,
@NonNull ButtonColors colors,
@NonNull TextButtonStyle style,
@NonNull ModifiersBuilders.Padding contentPadding
)
```
Opinionated ProtoLayout Material3 text button that offers a single slot to take content representing short text, for example `https://developer.android.com/reference/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).text(androidx.wear.protolayout.types.LayoutString,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Int,androidx.wear.protolayout.types.LayoutColor,kotlin.Boolean,kotlin.Boolean,kotlin.Boolean,kotlin.Int,kotlin.Int,kotlin.Int,kotlin.collections.List,kotlin.collections.List)`.
The button is usually either a circular shape with the same `https://developer.android.com/reference/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).textButton(androidx.wear.protolayout.ModifiersBuilders.Clickable,kotlin.Function1,androidx.wear.protolayout.modifiers.LayoutModifier,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.ButtonColors,androidx.wear.protolayout.material3.TextButtonStyle,androidx.wear.protolayout.ModifiersBuilders.Padding)` and `https://developer.android.com/reference/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).textButton(androidx.wear.protolayout.ModifiersBuilders.Clickable,kotlin.Function1,androidx.wear.protolayout.modifiers.LayoutModifier,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.ButtonColors,androidx.wear.protolayout.material3.TextButtonStyle,androidx.wear.protolayout.ModifiersBuilders.Padding)`, or highly recommended stadium shape occupying available space with `https://developer.android.com/reference/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).textButton(androidx.wear.protolayout.ModifiersBuilders.Clickable,kotlin.Function1,androidx.wear.protolayout.modifiers.LayoutModifier,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.ButtonColors,androidx.wear.protolayout.material3.TextButtonStyle,androidx.wear.protolayout.ModifiersBuilders.Padding)` and `https://developer.android.com/reference/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).textButton(androidx.wear.protolayout.ModifiersBuilders.Clickable,kotlin.Function1,androidx.wear.protolayout.modifiers.LayoutModifier,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.ButtonColors,androidx.wear.protolayout.material3.TextButtonStyle,androidx.wear.protolayout.ModifiersBuilders.Padding)` set to `https://developer.android.com/reference/androidx/wear/protolayout/DimensionBuilders#expand()` or `https://developer.android.com/reference/androidx/wear/protolayout/DimensionBuilders#weight(float)`, usually arranged with the `https://developer.android.com/reference/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).buttonGroup(androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,kotlin.Float,kotlin.Function1)`.
The button's `https://developer.android.com/reference/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).textButton(androidx.wear.protolayout.ModifiersBuilders.Clickable,kotlin.Function1,androidx.wear.protolayout.modifiers.LayoutModifier,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.ButtonColors,androidx.wear.protolayout.material3.TextButtonStyle,androidx.wear.protolayout.ModifiersBuilders.Padding)` default to using `https://developer.android.com/reference/androidx/wear/protolayout/material3/ColorScheme` from the `https://developer.android.com/reference/androidx/wear/protolayout/material3/MaterialScope` it's defined in, which defaults to `https://developer.android.com/reference/androidx/wear/protolayout/material3/package-summary#dynamicColorScheme(android.content.Context,androidx.wear.protolayout.material3.ColorScheme)`, meaning that the colors follow system theme if available on device. If not, or switched off by user, uses fallback `https://developer.android.com/reference/androidx/wear/protolayout/material3/ColorScheme` defined in its `https://developer.android.com/reference/androidx/wear/protolayout/material3/MaterialScope`.
See [common-layouts/tiles](https://developer.android.com/design/ui/wear/guides/foundations/common-layouts/tiles) and [bestpractices](https://developer.android.com/design/ui/wear/guides/surfaces/tiles/bestpractices) for more visuals and design recommendations.
```kotlin
import androidx.wear.protolayout.DimensionBuilders.expand
import androidx.wear.protolayout.material3.button
import androidx.wear.protolayout.material3.buttonGroup
import androidx.wear.protolayout.material3.icon
import androidx.wear.protolayout.material3.iconButton
import androidx.wear.protolayout.material3.materialScope
import androidx.wear.protolayout.material3.primaryLayout
import androidx.wear.protolayout.material3.text
import androidx.wear.protolayout.material3.textButton
import androidx.wear.protolayout.modifiers.LayoutModifier
import androidx.wear.protolayout.modifiers.background
import androidx.wear.protolayout.modifiers.clickable
import androidx.wear.protolayout.modifiers.contentDescription
import androidx.wear.protolayout.types.layoutString
materialScope(context, deviceConfiguration) {
primaryLayout(
mainSlot = {
buttonGroup {
buttonGroupItem {
iconButton(
onClick = clickable,
modifier =
LayoutModifier.contentDescription(
"Big button with image background"
),
width = expand(),
height = expand(),
iconContent = { icon("id1") },
)
}
buttonGroupItem {
iconButton(
onClick = clickable,
modifier =
LayoutModifier.contentDescription(
"Big button with image background"
),
width = expand(),
height = expand(),
shape = shapes.large,
iconContent = { icon("id2") },
)
}
buttonGroupItem {
textButton(
onClick = clickable,
modifier =
LayoutModifier.contentDescription(
"Big button with image background"
),
width = expand(),
height = expand(),
shape = shapes.large,
labelContent = { text("Dec".layoutString) },
)
}
}
}
)
}
```
| Parameters |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/ModifiersBuilders.Clickable onClick` | Associated `https://developer.android.com/reference/androidx/wear/protolayout/ModifiersBuilders.Clickable` for click events. When the button is clicked it will fire the associated action. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull Function1<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/material3/MaterialScope, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement> labelContent` | The text slot for content displayed in this button. It is recommended to use default styling that is automatically provided by only calling `https://developer.android.com/reference/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).text(androidx.wear.protolayout.types.LayoutString,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Int,androidx.wear.protolayout.types.LayoutColor,kotlin.Boolean,kotlin.Boolean,kotlin.Boolean,kotlin.Int,kotlin.Int,kotlin.Int,kotlin.collections.List,kotlin.collections.List)`. This should be small text, usually up to 3 characters text. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/modifiers/LayoutModifier modifier` | Modifiers to set to this element. It's highly recommended to set a content description using `https://developer.android.com/reference/androidx/wear/protolayout/modifiers/package-summary#(androidx.wear.protolayout.modifiers.LayoutModifier).contentDescription(kotlin.String,androidx.wear.protolayout.expression.DynamicBuilders.DynamicString)`. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/DimensionBuilders.ContainerDimension width` | The width of this button. It's highly recommended to set this to `https://developer.android.com/reference/androidx/wear/protolayout/DimensionBuilders#expand()` or `https://developer.android.com/reference/androidx/wear/protolayout/DimensionBuilders#weight(float)` |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/DimensionBuilders.ContainerDimension height` | The height of this button. It's highly recommended to set this to `https://developer.android.com/reference/androidx/wear/protolayout/DimensionBuilders#expand()` or `https://developer.android.com/reference/androidx/wear/protolayout/DimensionBuilders#weight(float)` |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/ModifiersBuilders.Corner shape` | Defines the button's shape, in other words the corner radius for this button. If changing these to radius smaller than `https://developer.android.com/reference/androidx/wear/protolayout/material3/Shapes#medium()`, it is important to adjusts the margins of `https://developer.android.com/reference/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).primaryLayout(kotlin.Function1,kotlin.Function1,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.ModifiersBuilders.Clickable,androidx.wear.protolayout.material3.PrimaryLayoutMargins)` used to accommodate for more space, for example by using `https://developer.android.com/reference/androidx/wear/protolayout/material3/PredefinedPrimaryLayoutMargins#(androidx.wear.protolayout.material3.MaterialScope).maxPrimaryLayoutMargins()`. Or, if the `https://developer.android.com/reference/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).textButton(androidx.wear.protolayout.ModifiersBuilders.Clickable,kotlin.Function1,androidx.wear.protolayout.modifiers.LayoutModifier,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.ButtonColors,androidx.wear.protolayout.material3.TextButtonStyle,androidx.wear.protolayout.ModifiersBuilders.Padding)` is set to `https://developer.android.com/reference/androidx/wear/protolayout/material3/Shapes#full()`, using `https://developer.android.com/reference/androidx/wear/protolayout/material3/PredefinedPrimaryLayoutMargins#(androidx.wear.protolayout.material3.MaterialScope).minPrimaryLayoutMargins()` can be considered. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/material3/ButtonColors colors` | The colors used for this button. If not set, `https://developer.android.com/reference/androidx/wear/protolayout/material3/ButtonDefaults#(androidx.wear.protolayout.material3.MaterialScope).filledButtonColors()` will be used as high emphasis button. Other recommended colors are `https://developer.android.com/reference/androidx/wear/protolayout/material3/ButtonDefaults#(androidx.wear.protolayout.material3.MaterialScope).filledTonalButtonColors()` and `https://developer.android.com/reference/androidx/wear/protolayout/material3/ButtonDefaults#(androidx.wear.protolayout.material3.MaterialScope).filledVariantButtonColors()`. If using custom colors, it is important to choose a color pair from same role to ensure accessibility with sufficient color contrast. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/material3/TextButtonStyle style` | The style which provides the attribute values required for constructing this text button and its inner content. It also provides default style for the inner content, that can be overridden by each content slot. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/ModifiersBuilders.Padding contentPadding` | The inner padding used to prevent inner content from being too close to the button's edge. It's highly recommended to keep the default. |