Build apps faster with our new App builder! Check it out →

Image

Common

Component in Compose Foundation

A composable that lays out and draws a given [ImageBitmap]. This will attempt to size the composable according to the [ImageBitmap]'s given width and height. However, an optional [Modifier] parameter can be provided to adjust sizing or draw additional content (ex. background). Any unspecified dimension will leverage the [ImageBitmap]'s size as a minimum constraint.

The following sample shows basic usage of an Image composable to position and draw an [ImageBitmap] on screen

Last updated:

Installation

dependencies {
   implementation("androidx.compose.foundation:foundation:1.8.0-alpha04")
}

Overloads

@Composable
@Deprecated(
    "Consider usage of the Image composable that consumes an optional FilterQuality parameter",
    level = DeprecationLevel.HIDDEN,
    replaceWith =
        ReplaceWith(
            expression =
                "Image(bitmap, contentDescription, modifier, alignment, contentScale, " +
                    "alpha, colorFilter, DefaultFilterQuality)",
            "androidx.compose.foundation",
            "androidx.compose.ui.graphics.DefaultAlpha",
            "androidx.compose.ui.Alignment",
            "androidx.compose.ui.graphics.drawscope.DrawScope.Companion.DefaultFilterQuality",
            "androidx.compose.ui.layout.ContentScale.Fit"
        )
)
@NonRestartableComposable
fun Image(
    bitmap: ImageBitmap,
    contentDescription: String?,
    modifier: Modifier = Modifier,
    alignment: Alignment = Alignment.Center,
    contentScale: ContentScale = ContentScale.Fit,
    alpha: Float = DefaultAlpha,
    colorFilter: ColorFilter? = null
)

Parameters

namedescription
bitmapThe [ImageBitmap] to draw
contentDescriptiontext used by accessibility services to describe what this image represents. This should always be provided unless this image is used for decorative purposes, and does not represent a meaningful action that a user can take. This text should be localized, such as by using [androidx.compose.ui.res.stringResource] or similar
modifierModifier used to adjust the layout algorithm or draw decoration content (ex. background)
alignmentOptional alignment parameter used to place the [ImageBitmap] in the given bounds defined by the width and height
contentScaleOptional scale parameter used to determine the aspect ratio scaling to be used if the bounds are a different size from the intrinsic size of the [ImageBitmap]
alphaOptional opacity to be applied to the [ImageBitmap] when it is rendered onscreen
colorFilterOptional ColorFilter to apply for the [ImageBitmap] when it is rendered onscreen
@Composable
@NonRestartableComposable
fun Image(
    bitmap: ImageBitmap,
    contentDescription: String?,
    modifier: Modifier = Modifier,
    alignment: Alignment = Alignment.Center,
    contentScale: ContentScale = ContentScale.Fit,
    alpha: Float = DefaultAlpha,
    colorFilter: ColorFilter? = null,
    filterQuality: FilterQuality = DefaultFilterQuality
)

Parameters

namedescription
bitmapThe [ImageBitmap] to draw
contentDescriptiontext used by accessibility services to describe what this image represents. This should always be provided unless this image is used for decorative purposes, and does not represent a meaningful action that a user can take. This text should be localized, such as by using [androidx.compose.ui.res.stringResource] or similar
modifierModifier used to adjust the layout algorithm or draw decoration content (ex. background)
alignmentOptional alignment parameter used to place the [ImageBitmap] in the given bounds defined by the width and height
contentScaleOptional scale parameter used to determine the aspect ratio scaling to be used if the bounds are a different size from the intrinsic size of the [ImageBitmap]
alphaOptional opacity to be applied to the [ImageBitmap] when it is rendered onscreen
colorFilterOptional ColorFilter to apply for the [ImageBitmap] when it is rendered onscreen
filterQualitySampling algorithm applied to the [bitmap] when it is scaled and drawn into the destination. The default is [FilterQuality.Low] which scales using a bilinear sampling algorithm
@Composable
@NonRestartableComposable
fun Image(
    imageVector: ImageVector,
    contentDescription: String?,
    modifier: Modifier = Modifier,
    alignment: Alignment = Alignment.Center,
    contentScale: ContentScale = ContentScale.Fit,
    alpha: Float = DefaultAlpha,
    colorFilter: ColorFilter? = null
)

Parameters

namedescription
imageVectorThe [ImageVector] to draw
contentDescriptiontext used by accessibility services to describe what this image represents. This should always be provided unless this image is used for decorative purposes, and does not represent a meaningful action that a user can take. This text should be localized, such as by using [androidx.compose.ui.res.stringResource] or similar
modifierModifier used to adjust the layout algorithm or draw decoration content (ex. background)
alignmentOptional alignment parameter used to place the [ImageVector] in the given bounds defined by the width and height
contentScaleOptional scale parameter used to determine the aspect ratio scaling to be used if the bounds are a different size from the intrinsic size of the [ImageVector]
alphaOptional opacity to be applied to the [ImageVector] when it is rendered onscreen
colorFilterOptional ColorFilter to apply for the [ImageVector] when it is rendered onscreen
@Composable
fun Image(
    painter: Painter,
    contentDescription: String?,
    modifier: Modifier = Modifier,
    alignment: Alignment = Alignment.Center,
    contentScale: ContentScale = ContentScale.Fit,
    alpha: Float = DefaultAlpha,
    colorFilter: ColorFilter? = null
)

Parameters

namedescription
painterto draw
contentDescriptiontext used by accessibility services to describe what this image represents. This should always be provided unless this image is used for decorative purposes, and does not represent a meaningful action that a user can take. This text should be localized, such as by using [androidx.compose.ui.res.stringResource] or similar
modifierModifier used to adjust the layout algorithm or draw decoration content (ex. background)
alignmentOptional alignment parameter used to place the [Painter] in the given bounds defined by the width and height.
contentScaleOptional scale parameter used to determine the aspect ratio scaling to be used if the bounds are a different size from the intrinsic size of the [Painter]
alphaOptional opacity to be applied to the [Painter] when it is rendered onscreen the default renders the [Painter] completely opaque
colorFilterOptional colorFilter to apply for the [Painter] when it is rendered onscreen

Code Examples

ImageSample

@Composable
fun ImageSample() {
    val ImageBitmap = createTestImage()
    // Lays out and draws an image sized to the dimensions of the ImageBitmap
    Image(bitmap = ImageBitmap, contentDescription = "Localized description")
}

BitmapPainterSubsectionSample

@Composable
fun BitmapPainterSubsectionSample() {
    val ImageBitmap = createTestImage()
    // Lays out and draws an image sized to the rectangular subsection of the ImageBitmap
    Image(
        painter = BitmapPainter(ImageBitmap, IntOffset(10, 12), IntSize(50, 60)),
        contentDescription = "Localized description"
    )
}

BitmapPainterSample

@Composable
fun BitmapPainterSample() {
    val customPainter = remember {
        object : Painter() {

            override val intrinsicSize: Size
                get() = Size(100.0f, 100.0f)

            override fun DrawScope.onDraw() {
                drawRect(color = Color.Cyan)
            }
        }
    }

    Image(
        painter = customPainter,
        contentDescription = "Localized description",
        modifier = Modifier.size(100.dp, 100.dp)
    )
}
by @alexstyl