Avatar
A circular image element backed by Coil3 with automatic fallback text, custom loading, and error states.
Avatar renders a circular, border-outlined container that loads a remote image via Coil3's SubcomposeAsyncImage. When model is null or the image fails to load, the component falls back to displaying fallbackText (typically initials) on the theme's muted background. Custom composables can be supplied for the loading and error states independently.
Basic usage
Fallback text
Pass model = null to always show the initials placeholder. Useful for users who have not set a profile picture.
Custom size
Use size to scale the avatar. The fallback text size scales proportionally at 40 % of the given size.
Custom loading state
Supply loadingContent to replace the default fallback-text placeholder shown while the image is being fetched.
Custom error fallback
Supply errorContent to render a custom composable when the image URL is invalid or the request fails. When omitted, fallbackText is shown instead.
API reference
Avatar
| Parameter | Type | Default | Description |
|---|---|---|---|
model | Any? | — | Coil3 image data — a URL string, Uri, ImageRequest, or null to always show the fallback. |
modifier | Modifier | Modifier | Applied to the outer Box container after size and clip. |
size | Dp | 40.dp | Diameter of the circular avatar. Fallback text scales at 40 % of this value. |
contentDescription | String? | null | Accessibility description for the image. |
fallbackText | String | — | Text shown when model is null, the image is loading (and no loadingContent is set), or the image fails (and no errorContent is set). |
loadingContent | (@Composable () -> Unit)? | null | Composable shown while the image is loading. Falls back to fallbackText when null. |
errorContent | (@Composable () -> Unit)? | null | Composable shown when the image fails to load. Falls back to fallbackText when null. |
contentScale | ContentScale | ContentScale.Crop | Scaling strategy for the loaded image inside the circular bounds. |