Image
Picture or icon whose accessibility comes down to one decision about what it means. A meaningful image is named for what it conveys, a decorative one passes null and leaves the tree, and an empty string is not decorative.
Selection
The criteria an agent checks before retrieving this component.
Use when
- Use when a picture or icon conveys information the surrounding text does not (e.g., a product photo on a detail screen, a standalone status icon, a chart).
- Use when an image is decorative and needs to be kept out of the way of a screen reader (e.g., a background illustration, an icon beside text that already says the same thing).
- Use when an image contains text, such as a logo or a wordmark.
Try a different component when
- Do not use when the icon is the content of a control the user taps (use
button.basic). - Do not use when the image is the thumbnail inside a list row (use
list-item.basic). - Do not use when the image is a tile in a horizontally scrolling strip (use
content-shelf.basic). - Do not use when the graphic shows that work is in progress (use
progress-indicator.basic).
Must Haves
Non-negotiable structure. Every generated instance must satisfy these rules.
- Decide whether the image carries meaning before writing it.
ImageandIcontakecontentDescriptionas a required parameter with no default, so every call site makes this choice explicitly (global.icon). - Give a meaningful image a
contentDescriptionnaming what it conveys in context, not what it depicts. A green check beside an order is "Delivered", not "Green check mark". - Give a decorative image
contentDescription = null. It then applies no semantics at all and TalkBack does not stop on it. - Pass
nullfor a decorative image, never"". An empty string still appliesRole.Imagewith an empty name, so the image stays in the tree. - Give an image of text a
contentDescriptionthat matches the text it shows (e.g., a wordmark logo named with the company name). - Give a complex image, such as a chart or a map, a short
contentDescriptionstating its conclusion (e.g., "Weekly views, rising from 1,200 to 3,400"), and make the full data available as visible text or a table nearby, or one step away on another screen (e.g., a "View data" action beside the chart). - Name a meaningful graphic drawn without
ImageorIconyourself.Modifier.paint,Canvas, andModifier.backgroundapply no semantics, so setModifier.semantics { contentDescription = "..."; role = Role.Image }on it, or it does not exist to a screen reader. - Convey a status shown by an icon in more than its color. A red dot and a green dot that differ only in hue need a
contentDescriptioneach, or visible text beside them (global.use-of-color).
Donts
Avoid these accessibility and UX barriers.
- Do not pass
contentDescription = ""to mark an image decorative. Usenull. - Do not describe the artwork when the image stands for something. A red circled cross on a failed upload is named "Upload failed", not "Red X".
- Do not name an image whose meaning the adjacent text already states. Both reach the user, and they hear the same thing twice.
- Do not open a description with "Image of" or "Picture of".
ImageandIconapplyRole.Image, and TalkBack announces the role on its own. - Do not use a file name, an asset ID, or a generic word such as "image" or "icon" as the description.
- Do not render text as an image where a
Textwould do. Text in a bitmap does not scale with the user's font size (global.text-scaling). - Do not use
Modifier.semantics { invisibleToUser() }to hide a graphic. It is deprecated;hideFromAccessibility()replaces it, and for anImageorIconpassingnullis simpler than either.
Customizable
Alternatives and options that give the AI agent some room to move.
- The image may be loaded from resources, a bitmap, a vector, or the network through a library such as Coil's
AsyncImage. Every one of these takes the samecontentDescriptionparameter with the same meaning. contentScale, clipping, and shape are visual choices with no effect on the accessible name.- A decorative illustration assembled from several drawn shapes may be removed in one step with
Modifier.semantics { hideFromAccessibility() }on its container, instead of handling each shape. - A long description may live in visible text below the image, or on a screen the user reaches from it, rather than in
contentDescription, provided thecontentDescriptionstill states what the image is.
Golden Pattern
The tested reference implementation. Agents start from this shape and adapt to the developer’s codebase and context.
@Composable
fun ImageExamples(views: List<Int>) {
Column {
Image(
painter = painterResource(R.drawable.skillet_hero),
contentDescription = "Cast iron skillet, 12 inch, pre-seasoned"
)
Image(
painter = painterResource(R.drawable.kitchen_illustration),
contentDescription = null
)
Row(verticalAlignment = Alignment.CenterVertically) {
Icon(Icons.Filled.CheckCircle, contentDescription = null)
Text("Delivered September 26")
}
Icon(Icons.Filled.Error, contentDescription = "Upload failed")
Image(
painter = painterResource(R.drawable.wordmark),
contentDescription = "Acme Kitchen"
)
Canvas(
modifier = Modifier
.fillMaxWidth()
.height(160.dp)
.semantics {
contentDescription = "Weekly views, rising from 1,200 to 3,400"
role = Role.Image
}
) {
// draw the line chart from `views`
}
}
}