# ImageKt

Added in 1.3.0

*** ** * ** ***


```
public final class ImageKt
```

<br />

*** ** * ** ***

## Summary

| ### Public methods |
|---|---|
| `static final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement` | `[avatarImage](https://developer.android.com/reference/androidx/wear/protolayout/material3/ImageKt#(androidx.wear.protolayout.material3.MaterialScope).avatarImage(kotlin.String,androidx.wear.protolayout.DimensionBuilders.ImageDimension,androidx.wear.protolayout.DimensionBuilders.ImageDimension,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Int))( @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/java/lang/String.html protoLayoutResourceId, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/DimensionBuilders.ImageDimension width, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/DimensionBuilders.ImageDimension height, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/modifiers/LayoutModifier modifier, int contentScaleMode )` **This method is deprecated.** Use avatarImage(ImageResource, String, ImageDimension, ImageDimension, LayoutModifier, Int) instead, in combination with \[androidx.wear.tiles.Material3TileService\] that creates scopes for you. |
| `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/ImageKt#(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)( @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/ResourceBuilders.ImageResource resource, https://developer.android.com/reference/java/lang/String.html protoLayoutResourceId, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/DimensionBuilders.ImageDimension width, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/DimensionBuilders.ImageDimension height, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/modifiers/LayoutModifier modifier, int contentScaleMode )` Returns the avatar image with the defined style which will be automatically registered as a resource. |
| `static final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement` | `[backgroundImage](https://developer.android.com/reference/androidx/wear/protolayout/material3/ImageKt#(androidx.wear.protolayout.material3.MaterialScope).backgroundImage(kotlin.String,androidx.wear.protolayout.modifiers.LayoutModifier,androidx.wear.protolayout.DimensionBuilders.ImageDimension,androidx.wear.protolayout.DimensionBuilders.ImageDimension,androidx.wear.protolayout.types.LayoutColor,kotlin.Int))( @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/java/lang/String.html protoLayoutResourceId, @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.ImageDimension width, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/DimensionBuilders.ImageDimension height, https://developer.android.com/reference/androidx/wear/protolayout/types/LayoutColor overlayColor, int contentScaleMode )` **This method is deprecated.** Use backgroundImage(ImageResource, String, LayoutModifier, ImageDimension, ImageDimension, LayoutColor?, Int) instead, in combination with \[androidx.wear.tiles.Material3TileService\] that creates scopes for you. |
| `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/ImageKt#(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)( @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/ResourceBuilders.ImageResource resource, https://developer.android.com/reference/java/lang/String.html protoLayoutResourceId, @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.ImageDimension width, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/DimensionBuilders.ImageDimension height, https://developer.android.com/reference/androidx/wear/protolayout/types/LayoutColor overlayColor, int contentScaleMode )` Returns the image background with the defined style which will be automatically registered as a resource. |

## Public methods

### avatarImage

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/Image.kt+function:avatarImage) Added in [1.3.0](https://developer.android.com/jetpack/androidx/releases/wear-protolayout#1.3.0) Deprecated in [1.4.2](https://developer.android.com/jetpack/androidx/releases/wear-protolayout#1.4.2)

```
public static final @NonNull LayoutElementBuilders.LayoutElement [avatarImage](https://developer.android.com/reference/androidx/wear/protolayout/material3/ImageKt#(androidx.wear.protolayout.material3.MaterialScope).avatarImage(kotlin.String,androidx.wear.protolayout.DimensionBuilders.ImageDimension,androidx.wear.protolayout.DimensionBuilders.ImageDimension,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Int))(
    @NonNull MaterialScope receiver,
    @NonNull String protoLayoutResourceId,
    @NonNull DimensionBuilders.ImageDimension width,
    @NonNull DimensionBuilders.ImageDimension height,
    @NonNull LayoutModifier modifier,
    int contentScaleMode
)
```

> [!CAUTION]
> **This method is deprecated.**   
> Use avatarImage(ImageResource, String, ImageDimension, ImageDimension, LayoutModifier, Int) instead, in combination with \[androidx.wear.tiles.Material3TileService\] that creates scopes for you.

Returns the avatar image with the defined style.

Material components such as `https://developer.android.com/reference/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).appCard(androidx.wear.protolayout.ModifiersBuilders.Clickable,kotlin.Function1,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Function1,kotlin.Function1,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.CardColors,kotlin.Function1,androidx.wear.protolayout.material3.AppCardStyle,androidx.wear.protolayout.ModifiersBuilders.Padding)` provide proper defaults for the small avatar image. In order to take advantage of those defaults, this should be used with the resource ID only: `avatarImage("id")`.

| Parameters |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html protoLayoutResourceId` | The protolayout resource id of the image. Node that, this is not an Android resource id. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/DimensionBuilders.ImageDimension width` | The width of an image. Usually, a small image that fit into the component's slot. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/DimensionBuilders.ImageDimension height` | The height of an image. Usually, a small image that fit into the component's slot. |
| `@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. |
| `int contentScaleMode` | The content scale mode for the image to define how image will adapt to the given size |

### avatarImage

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/Image.kt+function:avatarImage) Added in [1.4.2](https://developer.android.com/jetpack/androidx/releases/wear-protolayout#1.4.2)

```
public static final @NonNull LayoutElementBuilders.LayoutElement avatarImage(
    @NonNull MaterialScope receiver,
    @NonNull ResourceBuilders.ImageResource resource,
    String protoLayoutResourceId,
    @NonNull DimensionBuilders.ImageDimension width,
    @NonNull DimensionBuilders.ImageDimension height,
    @NonNull LayoutModifier modifier,
    int contentScaleMode
)
```

Returns the avatar image with the defined style which will be automatically registered as a resource.

Material components such as `https://developer.android.com/reference/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).appCard(androidx.wear.protolayout.ModifiersBuilders.Clickable,kotlin.Function1,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Function1,kotlin.Function1,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.CardColors,kotlin.Function1,androidx.wear.protolayout.material3.AppCardStyle,androidx.wear.protolayout.ModifiersBuilders.Padding)` provide proper defaults for the small avatar image. In order to take advantage of those defaults, this should be used with the resource ID only: `avatarImage(imageResource)`.

Note that, by using this method, there's no need to register resource for Tiles in `androidx.wear.tiles.TileService.onTileResourcesRequest`.

| Parameters |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/ResourceBuilders.ImageResource resource` | An Image resource, used in the layout in the place of this element. |
| `https://developer.android.com/reference/java/lang/String.html protoLayoutResourceId` | The optional protolayout resource id of the icon. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/DimensionBuilders.ImageDimension width` | The width of an image. Usually, a small image that fit into the component's slot. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/DimensionBuilders.ImageDimension height` | The height of an image. Usually, a small image that fit into the component's slot. |
| `@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. |
| `int contentScaleMode` | The content scale mode for the image to define how image will adapt to the given size |

| Throws |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-state-exception/index.html` | if this method is called without `https://developer.android.com/reference/androidx/wear/protolayout/ProtoLayoutScope` set to the `https://developer.android.com/reference/androidx/wear/protolayout/material3/MaterialScope`, i.e. when `https://developer.android.com/reference/androidx/wear/protolayout/material3/package-summary#materialScopeWithResources(android.content.Context,androidx.wear.protolayout.ProtoLayoutScope,androidx.wear.protolayout.DeviceParametersBuilders.DeviceParameters,kotlin.Boolean,androidx.wear.protolayout.material3.ColorScheme,kotlin.Function1)` wasn't used |

### backgroundImage

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/Image.kt+function:backgroundImage) Added in [1.3.0](https://developer.android.com/jetpack/androidx/releases/wear-protolayout#1.3.0) Deprecated in [1.4.2](https://developer.android.com/jetpack/androidx/releases/wear-protolayout#1.4.2)

```
public static final @NonNull LayoutElementBuilders.LayoutElement [backgroundImage](https://developer.android.com/reference/androidx/wear/protolayout/material3/ImageKt#(androidx.wear.protolayout.material3.MaterialScope).backgroundImage(kotlin.String,androidx.wear.protolayout.modifiers.LayoutModifier,androidx.wear.protolayout.DimensionBuilders.ImageDimension,androidx.wear.protolayout.DimensionBuilders.ImageDimension,androidx.wear.protolayout.types.LayoutColor,kotlin.Int))(
    @NonNull MaterialScope receiver,
    @NonNull String protoLayoutResourceId,
    @NonNull LayoutModifier modifier,
    @NonNull DimensionBuilders.ImageDimension width,
    @NonNull DimensionBuilders.ImageDimension height,
    LayoutColor overlayColor,
    int contentScaleMode
)
```

> [!CAUTION]
> **This method is deprecated.**   
> Use backgroundImage(ImageResource, String, LayoutModifier, ImageDimension, ImageDimension, LayoutColor?, Int) instead, in combination with \[androidx.wear.tiles.Material3TileService\] that creates scopes for you.

Returns the image background with the defined style.

Material components provide proper defaults for the background image. In order to take advantage of those defaults, this should be used with the resource ID only: `backgroundImage("id")`.

This image can have optional overlay on top of it, that is usually a dark color with opacity. This is highly recommended to be added when there's additional content like text on top of image, to improve readability.

If this is used in `https://developer.android.com/reference/androidx/wear/protolayout/material3/package-summary#(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)` as image button with no other content, `https://developer.android.com/reference/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).backgroundImage(kotlin.String,androidx.wear.protolayout.modifiers.LayoutModifier,androidx.wear.protolayout.DimensionBuilders.ImageDimension,androidx.wear.protolayout.DimensionBuilders.ImageDimension,androidx.wear.protolayout.types.LayoutColor,kotlin.Int)` can be omitted, and the overlay color on top of the image would be ignored.

| Parameters |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html protoLayoutResourceId` | The protolayout resource id of the image. Node that, this is not an Android 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. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/DimensionBuilders.ImageDimension width` | The width of an image. Usually, this matches the width of the parent component this is used in. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/DimensionBuilders.ImageDimension height` | The height of an image. Usually, this matches the height of the parent component this is used in. |
| `https://developer.android.com/reference/androidx/wear/protolayout/types/LayoutColor overlayColor` | The color used to provide the overlay over the image for better readability. It's recommended to use `https://developer.android.com/reference/androidx/wear/protolayout/material3/ColorScheme#background()` color with 60% opacity. If `null`, overlay would be ignored. |
| `int contentScaleMode` | The content scale mode for the image to define how image will adapt to the given size |

### backgroundImage

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/Image.kt+function:backgroundImage) Added in [1.4.2](https://developer.android.com/jetpack/androidx/releases/wear-protolayout#1.4.2)

```
public static final @NonNull LayoutElementBuilders.LayoutElement backgroundImage(
    @NonNull MaterialScope receiver,
    @NonNull ResourceBuilders.ImageResource resource,
    String protoLayoutResourceId,
    @NonNull LayoutModifier modifier,
    @NonNull DimensionBuilders.ImageDimension width,
    @NonNull DimensionBuilders.ImageDimension height,
    LayoutColor overlayColor,
    int contentScaleMode
)
```

Returns the image background with the defined style which will be automatically registered as a resource.

Material components provide proper defaults for the background image. In order to take advantage of those defaults, this should be used with the resource ID only: `backgroundImage(imageResource)`.

Note that, by using this method, there's no need to register resource for Tiles in `androidx.wear.tiles.TileService.onTileResourcesRequest`.

This image can have optional overlay on top of it, that is usually a dark color with opacity. This is highly recommended to be added when there's additional content like text on top of image, to improve readability.

If this is used in `https://developer.android.com/reference/androidx/wear/protolayout/material3/package-summary#(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)` as image button with no other content, `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)` can be omitted, and the overlay color on top of the image would be ignored.

| Parameters |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/ResourceBuilders.ImageResource resource` | An Image resource, used in the layout in the place of this element. |
| `https://developer.android.com/reference/java/lang/String.html protoLayoutResourceId` | The optional protolayout resource id of the icon. |
| `@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. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/DimensionBuilders.ImageDimension width` | The width of an image. Usually, this matches the width of the parent component this is used in. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/DimensionBuilders.ImageDimension height` | The height of an image. Usually, this matches the height of the parent component this is used in. |
| `https://developer.android.com/reference/androidx/wear/protolayout/types/LayoutColor overlayColor` | The color used to provide the overlay over the image for better readability. It's recommended to use `https://developer.android.com/reference/androidx/wear/protolayout/material3/ColorScheme#background()` color with 60% opacity. If `null`, overlay would be ignored. |
| `int contentScaleMode` | The content scale mode for the image to define how image will adapt to the given size |

| Throws |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-state-exception/index.html` | if this method is called without `https://developer.android.com/reference/androidx/wear/protolayout/ProtoLayoutScope` set to the `https://developer.android.com/reference/androidx/wear/protolayout/material3/MaterialScope`, i.e. when `https://developer.android.com/reference/androidx/wear/protolayout/material3/package-summary#materialScopeWithResources(android.content.Context,androidx.wear.protolayout.ProtoLayoutScope,androidx.wear.protolayout.DeviceParametersBuilders.DeviceParameters,kotlin.Boolean,androidx.wear.protolayout.material3.ColorScheme,kotlin.Function1)` wasn't used |