---
title: Avatar
description: An unstyled avatar component with image, fallback content, and caller-defined shape.
---



```kotlin expandable title="AvatarDemo.kt" githubUrl="https://github.com/composablehorizons/compose-unstyled/blob/main/demo/src/commonMain/kotlin/com/composeunstyled/demo/avatar/AvatarDemo.kt"
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.layout.ContentScale
import androidx.compose.ui.tooling.preview.Preview
import androidx.compose.ui.unit.dp
import com.composables.uripainter.rememberUriPainter
import com.composeunstyled.Text
import com.composeunstyled.UnstyledAvatar
import com.composeunstyled.demo.colors
import com.composeunstyled.demo.inputBackgroundToken
import com.composeunstyled.demo.surfaceToken
import com.composeunstyled.theme.Theme
import kotlin.time.Duration.Companion.milliseconds

@Preview
@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, Theme[colors][surfaceToken], CircleShape)
        .background(Theme[colors][inputBackgroundToken]),
      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, Theme[colors][surfaceToken], CircleShape)
        .background(Theme[colors][inputBackgroundToken]),
      contentScale = ContentScale.Crop,
    )
    UnstyledAvatar(
      painter = painter,
      underlay = {
        Text("CC")
      },
      contentDescription = "@coolcat",
      modifier = Modifier
        .size(56.dp)
        .clip(CircleShape)
        .border(1.dp, Theme[colors][surfaceToken], CircleShape)
        .background(Theme[colors][inputBackgroundToken]),
      contentScale = ContentScale.Crop,
    )
  }
}
```



## Features

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

## Installation

```kotlin
implementation("com.composables:composeunstyled-avatar:2.10.0")
```

## Anatomy

```kotlin
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.

```kotlin expandable
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.

```kotlin expandable
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. |