Images can be customized using properties on an `Image` composable
(`contentScale`, `colorFilter`). You can also apply the existing [`Modifiers`](https://developer.android.com/develop/ui/compose/modifiers-list)
to apply different effects to your `Image`. Modifiers can be used on **any
Composable** , not just the `Image` composable, whereas `contentScale` and
`colorFilter` are explicit parameters on the `Image` composable.

## Content scale

Specify a `contentScale` option to crop or change how an image is scaled inside
its bounds. By default, if you don't specify a `contentScale` option,
`ContentScale.Fit` will be used.

In the example below, the Image composable is restricted to a 150dp size with a
border and the background is set to yellow on the `Image` composable to showcase
the different `ContentScale` options in the table below.


```kotlin
val imageModifier = Modifier
    .size(150.dp)
    .border(BorderStroke(1.dp, Color.Black))
    .background(Color.Yellow)
Image(
    painter = painterResource(id = R.drawable.dog),
    contentDescription = stringResource(id = R.string.dog_content_description),
    contentScale = ContentScale.Fit,
    modifier = imageModifier
)https://github.com/android/snippets/blob/1da1d9d645cd1a8e693981900e04d6bc32287a5c/compose/snippets/src/main/java/com/example/compose/snippets/images/CustomizeImageSnippets.kt#L101-L110
```

<br />

Setting different `ContentScale` options will result in different outputs. Below
is a table that can help in choosing the correct `ContentScale` mode you
require:

|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **Source image**                                                                                                                                                                                                                                                                                                                  | ![Portrait source image](https://developer.android.com/static/develop/ui/compose/images/graphics-sourceimagesmall.jpg)                                                                                                                                                                                                                                                                                       | ![Source image landscape](https://developer.android.com/static/develop/ui/compose/images/graphics-sourceimageland.jpg)                                                                                                                                                                                                                                                                                 |
| `ContentScale`                                                                                                                                                                                                                                                                                                                    | Result - Portrait Image:                                                                                                                                                                                                                                                                                                                                                                                     | Result - Landscape Image:                                                                                                                                                                                                                                                                                                                                                                              |
| `ContentScale.Fit`: Scale the image uniformly, keeping the aspect ratio (default). If content is smaller than the size, the image is scaled up to fit the bounds.                                                                                                                                                                 | ![ContentScale.Fit portrait](https://developer.android.com/static/develop/ui/compose/images/graphics-CSF-Portrait.png)                                                                                                                                                                                                                                                                                       | ![ContentScale.Fit landscape](https://developer.android.com/static/develop/ui/compose/images/graphics-CSF-Land.png)                                                                                                                                                                                                                                                                                    |
| `ContentScale.Crop`: Center crop the image into the available space.                                                                                                                                                                                                                                                              | ![ContentScale.Crop portrait](https://developer.android.com/static/develop/ui/compose/images/graphics-CSC-Portrait.png)                                                                                                                                                                                                                                                                                      | ![ContentScale.Crop landscape](https://developer.android.com/static/develop/ui/compose/images/graphics-CSC-Land.png)                                                                                                                                                                                                                                                                                   |
| `ContentScale.FillHeight`: Scale the source maintaining the aspect ratio so that the bounds match the destination height.                                                                                                                                                                                                         | ![ContentScale.FillHeight portrait](https://developer.android.com/static/develop/ui/compose/images/graphics-CSFH-Portrait.png)                                                                                                                                                                                                                                                                               | ![ContentScale.FillHeight landscape](https://developer.android.com/static/develop/ui/compose/images/graphics-CSFH-Land.png)                                                                                                                                                                                                                                                                            |
| `ContentScale.FillWidth`: Scale the source maintaining the aspect ratio so that the bounds match the destination width.                                                                                                                                                                                                           | ![ContentScale.FillWidth portrait](https://developer.android.com/static/develop/ui/compose/images/graphics-CSFW-Portrait.png)                                                                                                                                                                                                                                                                                | ![ContentScale.FillWidth landscape](https://developer.android.com/static/develop/ui/compose/images/graphics-CSFW-Land.png)                                                                                                                                                                                                                                                                             |
| `ContentScale.FillBounds`: Scale the content vertically and horizontally **non-uniformly** to fill the destination bounds. (Note: This will distort images if you place them in containers that do not match the exact ratio of the image)                                                                                        | ![ContentScale.FillBounds portrait](https://developer.android.com/static/develop/ui/compose/images/graphics-CSFB-Portrait.png)                                                                                                                                                                                                                                                                               | ![ContentScale.FillBounds landscape](https://developer.android.com/static/develop/ui/compose/images/graphics-CSFB-Land.png)                                                                                                                                                                                                                                                                            |
| `ContentScale.Inside`: Scale the source to maintain the aspect ratio inside the destination bounds. If the source is smaller than or equal to the destination in both dimensions, it behaves similarly to \`None\`. Content will always be contained within the bounds. If content is smaller than bounds, no scaling will apply. | Source image bigger than bounds: ![ContentScale.Inside portrait, source image larger than bounds](https://developer.android.com/static/develop/ui/compose/images/graphics-biggerbounds-Portrait.png) Source image smaller than bounds: ![ContentScale.Inside portrait, source image smaller than bounds](https://developer.android.com/static/develop/ui/compose/images/graphics-smallerbounds-Portrait.png) | Source image bigger than bounds: ![ContentScale.Inside landscape, source image larger than bounds](https://developer.android.com/static/develop/ui/compose/images/graphics-biggerbounds-Land.png) Source image smaller than bounds: ![ContentScale.Inside landscape, source image smaller than bounds](https://developer.android.com/static/develop/ui/compose/images/graphics-smallerbounds-Land.png) |
| `ContentScale.None`: Don't apply any scaling to the source. If the content is smaller than destination bounds, it won't be scaled up to fit the area.                                                                                                                                                                             | Source image bigger than bounds: ![ContentScale.None portrait, source image larger than bounds](https://developer.android.com/static/develop/ui/compose/images/graphics-none-Portrait.png) Source image smaller than bounds: ![ContentScale.None portrait, source image smaller than bounds](https://developer.android.com/static/develop/ui/compose/images/graphics-smallerbounds-Portrait.png)             | Source image bigger than bounds: ![ContentScale.None landscape, source image larger than bounds](https://developer.android.com/static/develop/ui/compose/images/graphics-none-Land.png) Source image smaller than bounds: ![ContentScale.None landscape, source image smaller than bounds](https://developer.android.com/static/develop/ui/compose/images/graphics-smallerbounds-Land.png)             |

## Clip an `Image` composable to a shape

To make an image fit into a shape, use the built-in `clip` modifier.
To crop an image into a circle shape, use `Modifier.clip(CircleShape)`:


```kotlin
Image(
    painter = painterResource(id = R.drawable.dog),
    contentDescription = stringResource(id = R.string.dog_content_description),
    contentScale = ContentScale.Crop,
    modifier = Modifier
        .size(200.dp)
        .clip(CircleShape)
)https://github.com/android/snippets/blob/1da1d9d645cd1a8e693981900e04d6bc32287a5c/compose/snippets/src/main/java/com/example/compose/snippets/images/CustomizeImageSnippets.kt#L118-L125
```

<br />

![Clipping an image with CircleShape](https://developer.android.com/static/develop/ui/compose/images/graphics-clipcircle.png) **Figure 1**: Clipping an image with CircleShape

Rounded corner shape - use `Modifier.clip(RoundedCornerShape(16.dp)`) with the
size of the corners you want to be rounded:


```kotlin
Image(
    painter = painterResource(id = R.drawable.dog),
    contentDescription = stringResource(id = R.string.dog_content_description),
    contentScale = ContentScale.Crop,
    modifier = Modifier
        .size(200.dp)
        .clip(RoundedCornerShape(16.dp))
)https://github.com/android/snippets/blob/1da1d9d645cd1a8e693981900e04d6bc32287a5c/compose/snippets/src/main/java/com/example/compose/snippets/images/CustomizeImageSnippets.kt#L133-L140
```

<br />

![Clipping an image with RoundedCornerShape](https://developer.android.com/static/develop/ui/compose/images/graphics-roundedcorners.png) **Figure 2**: Clipping an image with RoundedCornerShape

You can also create your own clipping shape by extending `Shape`, and providing
a `Path` for the shape to clip around:


```kotlin
class SquashedOval : Shape {
    override fun createOutline(
        size: Size,
        layoutDirection: LayoutDirection,
        density: Density
    ): Outline {
        val path = Path().apply {
            // We create an Oval that starts at ¼ of the width, and ends at ¾ of the width of the container.
            addOval(
                Rect(
                    left = size.width / 4f,
                    top = 0f,
                    right = size.width * 3 / 4f,
                    bottom = size.height
                )
            )
        }
        return Outline.Generic(path = path)
    }
}

Image(
    painter = painterResource(id = R.drawable.dog),
    contentDescription = stringResource(id = R.string.dog_content_description),
    contentScale = ContentScale.Crop,
    modifier = Modifier
        .size(200.dp)
        .clip(SquashedOval())
)https://github.com/android/snippets/blob/1da1d9d645cd1a8e693981900e04d6bc32287a5c/compose/snippets/src/main/java/com/example/compose/snippets/images/CustomizeImageSnippets.kt#L148-L176
```

<br />

![Clipping an image with custom path shape](https://developer.android.com/static/develop/ui/compose/images/graphics-customcrop.png) **Figure 3**: Clipping an image with custom path shape

## Add a border to an `Image` composable

A common operation is to combine the `Modifier.border()` with `Modifier.clip()`
to create a border around an image:


```kotlin
val borderWidth = 4.dp
Image(
    painter = painterResource(id = R.drawable.dog),
    contentDescription = stringResource(id = R.string.dog_content_description),
    contentScale = ContentScale.Crop,
    modifier = Modifier
        .size(150.dp)
        .border(
            BorderStroke(borderWidth, Color.Yellow),
            CircleShape
        )
        .padding(borderWidth)
        .clip(CircleShape)
)https://github.com/android/snippets/blob/1da1d9d645cd1a8e693981900e04d6bc32287a5c/compose/snippets/src/main/java/com/example/compose/snippets/images/CustomizeImageSnippets.kt#L184-L197
```

<br />

![Clip an image and provide a border around it](https://developer.android.com/static/develop/ui/compose/images/graphics-border.png) **Figure 4**: Clip an image and provide a border around it

If you wish to create a gradient border, you can use the [`Brush`](https://developer.android.com/reference/kotlin/androidx/compose/ui/graphics/Brush) API to
draw a rainbow gradient border around the image:


```kotlin
val rainbowColorsBrush = remember {
    Brush.sweepGradient(
        listOf(
            Color(0xFF9575CD),
            Color(0xFFBA68C8),
            Color(0xFFE57373),
            Color(0xFFFFB74D),
            Color(0xFFFFF176),
            Color(0xFFAED581),
            Color(0xFF4DD0E1),
            Color(0xFF9575CD)
        )
    )
}
val borderWidth = 4.dp
Image(
    painter = painterResource(id = R.drawable.dog),
    contentDescription = stringResource(id = R.string.dog_content_description),
    contentScale = ContentScale.Crop,
    modifier = Modifier
        .size(150.dp)
        .border(
            BorderStroke(borderWidth, rainbowColorsBrush),
            CircleShape
        )
        .padding(borderWidth)
        .clip(CircleShape)
)https://github.com/android/snippets/blob/1da1d9d645cd1a8e693981900e04d6bc32287a5c/compose/snippets/src/main/java/com/example/compose/snippets/images/CustomizeImageSnippets.kt#L205-L232
```

<br />

![Rainbow gradient circle border](https://developer.android.com/static/develop/ui/compose/images/graphics-gradientborder.png) **Figure 5**: Rainbow gradient circle border

## Set a custom aspect ratio

To transform an image into a custom aspect ratio, use
`Modifier.aspectRatio(16f/9f)` to provide a custom ratio for an image (or any
composable for that matter).


```kotlin
Image(
    painter = painterResource(id = R.drawable.dog),
    contentDescription = stringResource(id = R.string.dog_content_description),
    modifier = Modifier.aspectRatio(16f / 9f)
)https://github.com/android/snippets/blob/1da1d9d645cd1a8e693981900e04d6bc32287a5c/compose/snippets/src/main/java/com/example/compose/snippets/images/CustomizeImageSnippets.kt#L240-L244
```

<br />

![Using Modifier.aspectRatio(16f/9f) on Image](https://developer.android.com/static/develop/ui/compose/images/graphics-aspectratio.png) **Figure 6** : Using `Modifier.aspectRatio(16f/9f)` on Image

## Color filter - Transform pixel colors of image

The Image composable has a `colorFilter` parameter that can change the output of
individual pixels of your image.

### Tinting an image

Using `ColorFilter.tint(color, blendMode)` will apply a blend mode with the
given color onto your `Image` composable. `ColorFilter.tint(color, blendMode)`
uses `BlendMode.SrcIn` to tint content, meaning that the color supplied will be
shown, where the image is displayed on screen. This is useful for icons and
vectors that need to be themed differently.


```kotlin
Image(
    painter = painterResource(id = R.drawable.baseline_directions_bus_24),
    contentDescription = stringResource(id = R.string.bus_content_description),
    colorFilter = ColorFilter.tint(Color.Yellow)
)https://github.com/android/snippets/blob/1da1d9d645cd1a8e693981900e04d6bc32287a5c/compose/snippets/src/main/java/com/example/compose/snippets/images/CustomizeImageSnippets.kt#L252-L256
```

<br />

![ColorFilter.tint applied with BlendMode.SrcIn](https://developer.android.com/static/develop/ui/compose/images/graphics-bus.png) **Figure 7**: ColorFilter.tint applied with BlendMode.SrcIn

Other `BlendMode`'s result in different effects. For example, setting
`BlendMode.Darken` with a `Color.Green` on an image produces the following
result:


```kotlin
Image(
    painter = painterResource(id = R.drawable.dog),
    contentDescription = stringResource(id = R.string.dog_content_description),
    colorFilter = ColorFilter.tint(Color.Green, blendMode = BlendMode.Darken)
)https://github.com/android/snippets/blob/1da1d9d645cd1a8e693981900e04d6bc32287a5c/compose/snippets/src/main/java/com/example/compose/snippets/images/CustomizeImageSnippets.kt#L264-L268
```

<br />

![Color.Green tint with BlendMode.Darken](https://developer.android.com/static/develop/ui/compose/images/graphics-blendmode.png) **Figure 8**: Color.Green tint with BlendMode.Darken

See [BlendMode reference documentation](https://developer.android.com/reference/kotlin/androidx/compose/ui/graphics/BlendMode) for more information on the
different blend modes available.

### Applying an `Image` filter with color matrix

Transform your image using the color matrix `ColorFilter` option. For example,
to apply a black and white filter onto your images you could use the
[`ColorMatrix`](https://developer.android.com/reference/kotlin/androidx/compose/ui/graphics/ColorMatrix) and set the saturation to `0f`.


```kotlin
Image(
    painter = painterResource(id = R.drawable.dog),
    contentDescription = stringResource(id = R.string.dog_content_description),
    colorFilter = ColorFilter.colorMatrix(ColorMatrix().apply { setToSaturation(0f) })
)https://github.com/android/snippets/blob/1da1d9d645cd1a8e693981900e04d6bc32287a5c/compose/snippets/src/main/java/com/example/compose/snippets/images/CustomizeImageSnippets.kt#L276-L280
```

<br />

![Color Matrix with saturation 0 (black and white image)](https://developer.android.com/static/develop/ui/compose/images/graphics-bw.png) **Figure 9**: Color Matrix with saturation 0 (black and white image)

#### Adjust contrast or brightness of an `Image` composable

To change the contrast and brightness of an image, you can use the
[`ColorMatrix`](https://developer.android.com/reference/kotlin/androidx/compose/ui/graphics/ColorMatrix) to change the values:


```kotlin
val contrast = 2f // 0f..10f (1 should be default)
val brightness = -180f // -255f..255f (0 should be default)
val colorMatrix = floatArrayOf(
    contrast, 0f, 0f, 0f, brightness,
    0f, contrast, 0f, 0f, brightness,
    0f, 0f, contrast, 0f, brightness,
    0f, 0f, 0f, 1f, 0f
)
Image(
    painter = painterResource(id = R.drawable.dog),
    contentDescription = stringResource(id = R.string.dog_content_description),
    colorFilter = ColorFilter.colorMatrix(ColorMatrix(colorMatrix))
)https://github.com/android/snippets/blob/1da1d9d645cd1a8e693981900e04d6bc32287a5c/compose/snippets/src/main/java/com/example/compose/snippets/images/CustomizeImageSnippets.kt#L288-L300
```

<br />

![Adjusted image brightness and contrast using ColorMatrix](https://developer.android.com/static/develop/ui/compose/images/graphics-colormatrix.png) **Figure 10**: Adjusted image brightness and contrast using ColorMatrix

#### Invert colors of an `Image` composable

To invert the colors of an image, set the [`ColorMatrix`](https://developer.android.com/reference/kotlin/androidx/compose/ui/graphics/ColorMatrix) to invert the
colors:


```kotlin
val colorMatrix = floatArrayOf(
    -1f, 0f, 0f, 0f, 255f,
    0f, -1f, 0f, 0f, 255f,
    0f, 0f, -1f, 0f, 255f,
    0f, 0f, 0f, 1f, 0f
)
Image(
    painter = painterResource(id = R.drawable.dog),
    contentDescription = stringResource(id = R.string.dog_content_description),
    colorFilter = ColorFilter.colorMatrix(ColorMatrix(colorMatrix))
)https://github.com/android/snippets/blob/1da1d9d645cd1a8e693981900e04d6bc32287a5c/compose/snippets/src/main/java/com/example/compose/snippets/images/CustomizeImageSnippets.kt#L308-L318
```

<br />

![Inverted colors on image](https://developer.android.com/static/develop/ui/compose/images/graphics-inverted.png) **Figure 11**: Inverted colors on image

## Blur an `Image` composable

To blur an image, use `Modifier.blur()`, supplying the `radiusX` and `radiusY`,
which specifies the blur radius in the horizontal and vertical direction
respectively.


```kotlin
Image(
    painter = painterResource(id = R.drawable.dog),
    contentDescription = stringResource(id = R.string.dog_content_description),
    contentScale = ContentScale.Crop,
    modifier = Modifier
        .size(150.dp)
        .blur(
            radiusX = 10.dp,
            radiusY = 10.dp,
            edgeTreatment = BlurredEdgeTreatment(RoundedCornerShape(8.dp))
        )
)https://github.com/android/snippets/blob/1da1d9d645cd1a8e693981900e04d6bc32287a5c/compose/snippets/src/main/java/com/example/compose/snippets/images/CustomizeImageSnippets.kt#L326-L337
```

<br />

![BlurEffect applied to image](https://developer.android.com/static/develop/ui/compose/images/graphics-blur.png) **Figure 12**: BlurEffect applied to image

When blurring `Images`, it is recommended to use `BlurredEdgeTreatment(Shape)`,
instead of `BlurredEdgeTreatment.Unbounded`, as the latter is used for blurring
of arbitrary renderings that are expected to render outside the bounds of the
original content. For images, it is likely that they won't render outside the
bounds of the content; whereas blurring a rounded rectangle may require this
distinction.

For example, if we set the `BlurredEdgeTreatment` to Unbounded on the above
image, the edges of the image appear blurred instead of sharp:


```kotlin
Image(
    painter = painterResource(id = R.drawable.dog),
    contentDescription = stringResource(id = R.string.dog_content_description),
    contentScale = ContentScale.Crop,
    modifier = Modifier
        .size(150.dp)
        .blur(
            radiusX = 10.dp,
            radiusY = 10.dp,
            edgeTreatment = BlurredEdgeTreatment.Unbounded
        )
        .clip(RoundedCornerShape(8.dp))
)https://github.com/android/snippets/blob/1da1d9d645cd1a8e693981900e04d6bc32287a5c/compose/snippets/src/main/java/com/example/compose/snippets/images/CustomizeImageSnippets.kt#L345-L357
```

<br />

![BlurEdgeTreatment.Unbounded](https://developer.android.com/static/develop/ui/compose/images/graphics-unbounded.png) **Figure 13**: BlurEdgeTreatment.Unbounded **Note:** The blur effect is only supported on Android 12 and above. Attempts to use this Modifier on older Android versions are ignored.

## Recommended for you

- Note: link text is displayed when JavaScript is off
- [Graphics Modifiers](https://developer.android.com/develop/ui/compose/graphics/draw/modifiers)
- [Loading images {:#loading-images}](https://developer.android.com/develop/ui/compose/graphics/images/loading)
- [Material icons {:#material-icons}](https://developer.android.com/develop/ui/compose/graphics/images/material)