Avatar - Compose Unstyled

An avatar primitive with image, fallback content, and caller-defined shape.

import androidx.compose.foundation.background
import androidx.compose.foundation.border
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.size
import androidx.compose.foundation.shape.CircleShape
import androidx.compose.runtime.Composable
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.draw.clip
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.layout.ContentScale
import androidx.compose.ui.unit.dp
import com.composables.uripainter.rememberUriPainter
import com.composeunstyled.Text
import com.composeunstyled.UnstyledAvatar
import kotlin.time.Duration.Companion.milliseconds

@Composable
fun AvatarDemo() {
  Row(
    modifier = Modifier.fillMaxSize(),
    horizontalArrangement = Arrangement.spacedBy(12.dp, Alignment.CenterHorizontally),
    verticalAlignment = Alignment.CenterVertically,
  ) {
    UnstyledAvatar(
      painter = null,
      underlay = {
        Text("CC")
      },
      contentDescription = "@coolcat",
      modifier = Modifier
        .size(32.dp)
        .clip(CircleShape)
        .border(1.dp, Color.White, CircleShape)
        .background(Color.LightGray),
      contentScale = ContentScale.Crop,
    )
    val painter = rememberUriPainter(
      "https://images.unsplash.com/photo-1533738363-b7f9aef128ce?q=80&w=1080",
      crossfade = 50.milliseconds,
    )

    UnstyledAvatar(
      painter = painter,
      underlay = {
        Text("CC")
      },
      contentDescription = "@coolcat",
      modifier = Modifier
        .size(48.dp)
        .clip(CircleShape)
        .border(1.dp, Color.White, CircleShape)
        .background(Color.LightGray),
      contentScale = ContentScale.Crop,
    )
    UnstyledAvatar(
      painter = painter,
      underlay = {
        Text("CC")
      },
      contentDescription = "@coolcat",
      modifier = Modifier
        .size(56.dp)
        .clip(CircleShape)
        .border(1.dp, Color.White, CircleShape)
        .background(Color.LightGray),
      contentScale = ContentScale.Crop,
    )
  }
}

Features

Use any kind of painter you want
Fallback content under the image

Installation

implementation("com.composables:composeunstyled-avatar")

Anatomy

val painter = rememberUriPainter(
  uri = "https://images.unsplash.com/photo-1533738363-b7f9aef128ce?q=80&w=1080",
  crossfade = 50.milliseconds,
)
UnstyledAvatar(
  painter = painter,
  contentDescription = "@coolcat",
  underlay = {
    BasicText("CC")
  },
)

Concepts

UnstyledAvatar represents the entire render avatar.
The underlay slot is placed behind the image, so it can provide initials or placeholder content when the painter fails to load the image or is null.

Accessibility

Pass a contentDescription when the avatar identifies a person, account, or brand. Use null when the avatar is decorative.

Code Examples

Showing initials until an image is available

Use the underlay parameter to provide fallback content behind the image. This is useful when the image may be missing or still loading.

UnstyledAvatar(
  painter = null,
  contentDescription = "@coolcat",
  underlay = {
    BasicText("CC")
  },
  modifier = Modifier
    .size(40.dp)
    .clip(CircleShape),
)

Cropping profile photos to the avatar bounds

Use the contentScale parameter to crop the image to the avatar container.

val painter = rememberUriPainter(
  uri = "https://images.unsplash.com/photo-1533738363-b7f9aef128ce?q=80&w=1080",
  crossfade = 50.milliseconds,
)
UnstyledAvatar(
  painter = painter,
  contentDescription = "@coolcat",
  contentScale = ContentScale.Crop,
  modifier = Modifier
    .size(40.dp)
    .clip(CircleShape),
)

API Reference

UnstyledAvatar

Parameter	Type	Description
`painter`	`Painter?`	The `Painter` to draw inside the avatar. Pass `null` to show only the fallback content.
`modifier`	`Modifier`	The `Modifier` applied to the avatar container.
`contentDescription`	`String?`	Accessibility text describing what the avatar represents.
`underlay`	`(() -> Unit)?`	Composable content placed behind the image, such as initials or a placeholder.
`contentScale`	`ContentScale`	Controls how the image is scaled inside the avatar bounds.