# UserAvatar

The [`UserAvatar`](https://github.com/GetStream/stream-chat-android/blob/main/stream-chat-android-compose/src/main/java/io/getstream/chat/android/compose/ui/components/avatar/UserAvatar.kt) component displays a user avatar. Based on the user state, it shows either the user's profile image or their initials with a gradient background. If the user is online and user presence is enabled for the app, an online indicator is displayed.

## Usage

To use the component, pass the `User` object to the `UserAvatar`:

```kotlin
UserAvatar(
    user = user,
    showOnlineIndicator = true,
    modifier = Modifier.size(36.dp)
)
```

Depending on the state within the `User` object, the snippet above will produce the next UI:

| ![Default UserAvatar Component](@chat-sdk/android/v6/_assets/compose_default_user_avatar_component.png) |
| ------------------------------------------------------------------------------------------------------- |

## Handling Actions

To handle clicks on `UserAvatar`, pass a lambda to the `onClick` parameter:

```kotlin
UserAvatar(
    user = user,
    modifier = Modifier.size(36.dp),
    onClick = {
        // Handle avatar clicks here
    }
)
```

## Customization

The `UserAvatar` exposes the following properties for customization:

```kotlin
@Composable
fun UserAvatar(
    user: User,
    modifier: Modifier = Modifier,
    shape: Shape = ChatTheme.shapes.avatar,
    textStyle: TextStyle = ChatTheme.typography.title3Bold,
    contentDescription: String? = null,
    showOnlineIndicator: Boolean = true,
    placeholderPainter: Painter? = null,
    errorPlaceholderPainter: Painter? = null,
    onlineIndicatorAlignment: OnlineIndicatorAlignment = OnlineIndicatorAlignment.TopEnd,
    initialsAvatarOffset: DpOffset = DpOffset(0.dp, 0.dp),
    onlineIndicator: @Composable BoxScope.() -> Unit = {
        OnlineIndicator(modifier = Modifier.align(onlineIndicatorAlignment.alignment))
    },
    onClick: (() -> Unit)? = null,
)
```

- `user`: The user whose avatar to display.
- `modifier`: Modifier for the root component. Useful for the component size, padding, background and similar.
- `shape`: The shape of the avatar.
- `textStyle`: The text style of the initials text.
- `contentDescription`: The content description of the avatar for accessibility.
- `showOnlineIndicator`: Whether to display the online status indicator.
- `placeholderPainter`: Custom placeholder image displayed while the avatar image is loading.
- `errorPlaceholderPainter`: Custom placeholder image displayed when the avatar image fails to load.
- `onlineIndicatorAlignment`: The alignment of the online indicator. Defaults to `OnlineIndicatorAlignment.TopEnd`.
- `initialsAvatarOffset`: The offset applied to the initials avatar.
- `onlineIndicator`: Custom composable that replaces the default online indicator.
- `onClick`: Handler for avatar click events.

### Custom Online Indicator

You can provide a custom online indicator composable:

```kotlin
UserAvatar(
    modifier = Modifier.size(48.dp),
    user = user,
    onlineIndicator = {
        Box(
            modifier = Modifier
                .align(Alignment.TopEnd)
                .size(12.dp)
                .background(Color.Blue, CircleShape)
        )
    }
)
```

The snippet above will produce an avatar with a blue online indicator:

| ![Custom UserAvatar Component](@chat-sdk/android/v6/_assets/compose_custom_user_avatar_component.png) |
| ----------------------------------------------------------------------------------------------------- |

### Custom Placeholder

You can provide custom placeholder images for loading and error states:

```kotlin
UserAvatar(
    modifier = Modifier.size(48.dp),
    user = user,
    placeholderPainter = painterResource(R.drawable.avatar_loading),
    errorPlaceholderPainter = painterResource(R.drawable.avatar_error)
)
```


---

This page was last updated at 2026-04-17T17:33:30.781Z.

For the most recent version of this documentation, visit [https://getstream.io/chat/docs/sdk/android/v6/compose/utility-components/user-avatar/](https://getstream.io/chat/docs/sdk/android/v6/compose/utility-components/user-avatar/).