suiss/ui
  • Docs
  • Components
  • Patterns
  • Interactions
  • Charts
  • Blocks
GitHubGet started
DocsComponentsPatternsInteractionsChartsBlocks
Components82
  • Overview
  • Accordion
  • Alert
  • Alert Dialog
  • Alert Sheet
  • Amount Input
  • Aspect Ratio
  • Attachment
  • Avatar
  • Badge
  • Bottom Bar
  • Breadcrumb
  • Bubble
  • Button
  • Button Group
  • Calendar
  • Card
  • Carousel
  • Chart
  • Checkbox
  • Chip
  • Collapsible
  • Combobox
  • Command
  • Context Menu
  • Dialog
  • Direction
  • Drawer
  • Dropdown Menu
  • Empty
  • FAB
  • Field
  • Fullscreen Menu
  • Haptics
  • Header
  • Hover Card
  • Icon
  • Input
  • Input Accessory Bar
  • Input Group
  • Input OTP
  • Item
  • Kbd
  • Keyboard Scroll View
  • Keypad
  • Label
  • Marker
  • Menubar
  • Message
  • Message Scroller
  • Native Select
  • Navigation Menu
  • Page Indicator
  • Pagination
  • Pin Pad
  • Popover
  • Progress
  • QR Scanner
  • Questionnaire
  • Radio Group
  • Resizable
  • Screen
  • Scroll Area
  • Select
  • Separator
  • Sheet
  • Sidebar
  • Signature Pad
  • Skeleton
  • Slider
  • Spinner
  • Switch
  • Tab Bar
  • Table
  • Tabs
  • Text
  • Textarea
  • Toast
  • Toggle
  • Toggle Group
  • Tooltip
  • Wheel Picker
  • Widget

suiss/ui · Component

Avatar

A circular image that represents a person, with initials or an icon when no image is available.

Avatar is an open-source component from suiss/ui for React, React Native, SwiftUI and Jetpack Compose. The @esuiss/ui CLI copies its source into your project, so you own the code.

Avatar wraps the avatar primitive of the chosen base. An Avatar contains an AvatarImage and an AvatarFallback; the fallback shows while the image is loading or if it fails to load. Add an AvatarBadge to show a status dot or icon in the bottom-end corner.

To show several people together, place avatars in an AvatarGroup, which overlaps them and rings each one with the background color. End the group with an AvatarGroupCount to indicate how many more people there are.

Installation

CLI

$ pnpm dlx shadcn@latest add @esuiss/avatar

Works in any project with a components.json. See Installation for the one-line registry setup. Or use the suiss/ui CLI:

$ pnpm dlx @esuiss/ui@latest add avatar

Manual

  1. Install the dependencies and add the cn helper:
$ pnpm add @base-ui/react
  1. Copy the source into components/ui/avatar.tsx:
  1. Update the import paths to match your project.

Usage

import { Avatar, AvatarImage, AvatarFallback, AvatarBadge, AvatarGroup, AvatarGroupCount } 
<Avatar

Always provide an AvatarFallback alongside AvatarImage, usually the person's initials. The fallback can also hold an icon, which scales to 60% of the avatar.

Set size on each Avatar. Inside an AvatarGroup, AvatarGroupCount matches the size of the avatars in the group automatically.

Examples

Fallback

Shows initials when no image is provided.

Fallback sizes

Initials fallbacks at every size.

Placeholder

Uses a person icon as the fallback at every size.

Sizes

Image avatars in the sm, default, lg and xl sizes.

With badge

Adds a check-mark status badge to each size.

Group

Overlaps several avatars and ends with a +4 count.

Group with icon count

A large group whose count shows a plus icon instead of a number.

API Reference

Anatomy9 parts
<Avatar>
<AvatarImage />
<AvatarFallback />
<AvatarBadge />
</Avatar>
<AvatarGroup>
<Avatar>
<AvatarImage
01

Avatar

The circular root that sets the size.

PropTypeDefaultDescription
size"default" | "sm" | "lg" | "xl""default"Diameter of the avatar: sm, default, lg or xl. Also scales the fallback text and badge.

Also accepts the props of the primitive part it wraps.

02

AvatarImage

The person's image, cropped to a circle.

Also accepts the props of the primitive part it wraps.

03

AvatarFallback

Content shown when the image is missing or still loading.

Also accepts the props of the primitive part it wraps.

04

AvatarBadge

A small status indicator pinned to the bottom-end corner.

Also accepts the props of React.ComponentProps<"span">.

05

AvatarGroup

A row that overlaps avatars with a ring between them.

Also accepts the props of React.ComponentProps<"div">.

06

AvatarGroupCount

A trailing circle that shows how many avatars are not displayed.

Also accepts the props of React.ComponentProps<"div">.

Accessibility

  • Give AvatarImage an alt that names the person.
  • AvatarBadge and AvatarGroupCount are plain elements; if they carry meaning, label them or describe the status in nearby text.

Notes

  • Styling hooks: data-slot="avatar", "avatar-image", "avatar-fallback", "avatar-badge", "avatar-group" and "avatar-group-count", plus data-size on the root.
  • AvatarBadge uses bg-primary by default; override it, for example with bg-green-500. At the sm size, icons inside the badge are hidden.
  • The fallback uses a vertical gradient of muted-foreground with text-primary-foreground.

Avatar is a round View that holds an AvatarImage and an AvatarFallback. The image stays hidden until it loads, and the fallback is shown while it loads or if it fails. Four sizes are available: sm, default, lg and xl; the fallback text, icons and badge scale with the size.

AvatarBadge adds a small status dot in the bottom-end corner, and AvatarGroup overlaps several avatars with an outline between them, with AvatarGroupCount for the remaining number.

Installation

$ pnpm dlx shadcn@latest add @esuiss-rn/avatar

See Installation for the components.json setup. Or use the suiss/ui CLI:

$ pnpm dlx @esuiss/ui@latest add avatar
$ pnpm dlx @esuiss/ui@latest add avatar --platform swift
NextBadgePreviousAttachment

On this page

  1. 01Installation
    • CLI
    • Manual
  2. 02Usage
  3. 03Examples
    • Fallback
    • Fallback sizes
    • Placeholder
    • Sizes
    • With badge
    • Group
    • Group with icon count
  4. 04API Reference
    • Avatar
    • AvatarImage
    • AvatarFallback
    • AvatarBadge
    • AvatarGroup
    • AvatarGroupCount
  5. 05Accessibility
  6. 06Notes
  7. 07Installation
    • Manual
  8. 08Usage
  9. 09Examples
    • Fallback
    • Sizes
    • Group
    • With badge
  10. 10API Reference
    • Avatar
    • AvatarImage
    • AvatarFallback
    • AvatarBadge
    • AvatarGroup
    • AvatarGroupCount
  11. 11Accessibility
  12. 12Notes
from
"@/components/ui/avatar"
>
<AvatarImage src={people[0].src} alt={people[0].name} />
<AvatarFallback>{people[0].initials}</AvatarFallback>
</Avatar>
/>
<AvatarFallback />
</Avatar>
<AvatarGroupCount />
</AvatarGroup>
$ pnpm dlx @esuiss/ui@latest add avatar --platform kotlin

The CLI also adds what it builds on: Icon, Text.

Manual

  1. Install the dependencies:
npx expo install cn

  1. Add the pieces it builds on: Icon, Text, and the primitives components/primitives/avatar.tsx, components/primitives/use-render.tsx.

  2. Copy the source into components/ui/avatar.tsx:

  1. Update the import paths to match your project.
  1. Install the dependencies:
npx expo install cn

  1. Add the pieces it builds on: Icon, Text, and the primitives components/primitives/avatar.tsx, components/primitives/use-render.tsx.

  2. Copy the source into components/ui/avatar.tsx:

  1. Update the import paths to match your project.

  1. Add the pieces it builds on: Icon, Text, and the primitives components/primitives/avatar.tsx, components/primitives/use-render.tsx.

  2. Copy the source into components/ui/avatar.tsx:

  1. Update the import paths to match your project.

  1. Target iOS 17 or later.

  2. Copy the theme files every view uses:

swift/Theme/Theme.swift
import SwiftUI
import UIKit

struct RGBA: Sendable {
  let red: CGFloat
  let green: CGFloat
  let blue: CGFloat
  let alpha: CGFloat

  init(_ hex: UInt32, _ alpha: CGFloat = 1) {
    red = CGFloat((hex >> 16) & 0xFF) / 255
    green = CGFloat((hex >> 8) & 0xFF) / 255
    blue = CGFloat(hex & 0xFF) / 255
    self.alpha = alpha
  }
swift/Theme/Tokens.swift
import SwiftUI

public enum EsuissColor {
  public static let background = Color.adaptive(light: .init(0xFFFFFF), dark: .init(0x000000))
  public static let foreground = Color.adaptive(light: .init(0x1D1D1F), dark: .init(0xF5F5F7))
  public static let card = Color.adaptive(light: .init(0xFFFFFF), dark: .init(0x1D1D1F))
  public static let cardForeground = Color.adaptive(light: .init(0x1D1D1F), dark: .init(0xF5F5F7))
  public static let popover = Color.adaptive(light: .init(0xFFFFFF), dark: .init(0x1D1D1F))
  public static let popoverForeground = Color.adaptive(light: .init(0x1D1D1F), dark: .init(0xF5F5F7))
  public static let primary = Color.adaptive(light: .init(0x0071E3), dark: .init(0x2997FF))
  public static let primaryForeground = Color.adaptive(light: .init(0xFFFFFF), dark: .init(0xFFFFFF))
  public static let secondary = Color.adaptive(light: .init(0x000000, 0.04), dark: .init(0xFFFFFF, 0.1))
  public static let secondaryForeground = Color.adaptive(light: .init(0x1D1D1F), dark: .init(0xF5F5F7))
  public static let muted = Color.adaptive(light: .init(0xF5F5F7), dark: .init(0x161617))
  public static let mutedForeground = Color.adaptive(light: .init(0x6E6E73), dark: .init(0xA1A1A6))
  public static let accent = Color.adaptive(light: .init(0x000000, 0.06), dark: .init(0xFFFFFF, 0.1))
  1. Copy the source and every file it uses:
swift/Components/TextVariant.swift
import SwiftUI

public enum TextVariant: CaseIterable, Sendable {
  case `default`, h1, h2, h3, h4, p, blockquote, code, lead, large, small, muted

  var style: TextStyle {
    switch self {
    case .h1: .xl3
    case .h2: .xl2
    case .h3: .xl
    case .h4, .lead, .large: .lg
    case .code, .small, .muted: .sm
    default: .base
    }
  }
  1. Add the files to your app target.
  1. Set minSdk to 24 or higher and add the dependencies:
build.gradle.kts
implementation(platform("androidx.compose:compose-bom:2026.09.00"))
implementation("androidx.compose.foundation:foundation")
implementation("androidx.compose.ui:ui")
  1. Copy the theme files every view uses:
kotlin/theme/Theme.kt
package com.esuiss.ui.theme

import androidx.compose.foundation.isSystemInDarkTheme
import androidx.compose.runtime.Composable
import androidx.compose.runtime.CompositionLocalProvider
import androidx.compose.runtime.Immutable
import androidx.compose.runtime.staticCompositionLocalOf
import androidx.compose.ui.Modifier
import androidx.compose.ui.draw.dropShadow
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.graphics.Shape
import androidx.compose.ui.graphics.shadow.Shadow as DropShadow
import androidx.compose.ui.text.TextStyle
import androidx.compose.ui.text.style.LineHeightStyle
import androidx.compose.ui.unit.Dp
import androidx.compose.ui.unit.DpOffset
kotlin/theme/Tokens.kt
package com.esuiss.ui.theme

import androidx.compose.runtime.Immutable
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.unit.dp

@Immutable
data class Colors(
    val background: Color,
    val foreground: Color,
    val card: Color,
    val cardForeground: Color,
    val popover: Color,
    val popoverForeground: Color,
    val primary: Color,
    val primaryForeground: Color,
  1. Copy the source and every file it uses:
kotlin/components/Avatar.kt
package com.esuiss.ui.components

import androidx.compose.foundation.Image
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.offset
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.layout.size
import androidx.compose.foundation.shape.CircleShape
import androidx.compose.foundation.text.BasicText
import androidx.compose.runtime.Composable
import androidx.compose.runtime.CompositionLocalProvider
import androidx.compose.runtime.staticCompositionLocalOf
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
kotlin/components/Content.kt
package com.esuiss.ui.components

import androidx.compose.runtime.compositionLocalOf
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.text.TextStyle
import androidx.compose.ui.unit.Dp
import androidx.compose.ui.unit.dp

val LocalContentStyle = compositionLocalOf { TextStyle.Default }

val LocalContentColor = compositionLocalOf { Color.Unspecified }

val LocalIconSize = compositionLocalOf { 20.dp }
  1. Update the com.esuiss.ui package names to match your project.

Usage

import { Avatar, AvatarImage, AvatarFallback, AvatarBadge, AvatarGroup, AvatarGroupCount } from "@/components/ui/avatar"
<Avatar>
  <AvatarImage
    alt="Ada Lovelace"
    source={{ uri: "https://i.pravatar.cc/150?img=5" }}
  />
  <AvatarFallback>
    <Text>AL</Text>
  </AvatarFallback>
</Avatar>

Give AvatarImage a source and an alt. Put initials or an Icon in AvatarFallback; plain strings are wrapped in Text. Use delay on the fallback to avoid a flash on fast connections, and onLoadingStatusChange on the image to react to loading.

Set size on each Avatar, and pass the same size to AvatarGroupCount. On the sm size, the badge hides its children and shows a plain dot.

Examples

Fallback

Initials shown when there is no image.

iOS
Avatar (fallback) on iOS in light modeAvatar (fallback) on iOS in dark mode
import { Avatar, AvatarFallback } from "@/components/ui/avatar"
import { Text } from "@/components/ui/text"

export function AvatarFallbackExample() {
  return (
    <Avatar accessibilityLabel="Alan Turing">
      <AvatarFallback>
        <Text>AT</Text>
      </AvatarFallback>
    </Avatar>
  )
}
import EsuissUI
import SwiftUI

struct AvatarFallbackExample: View {
  var body: some View {
    Avatar {
      AvatarFallback("AT")
    }
    .accessibilityLabel(Text("Alan Turing"))
  }
}
import androidx.compose.foundation.layout.Row
import androidx.compose.runtime.Composable
import androidx.compose.ui.Modifier
import androidx.compose.ui.semantics.contentDescription
import androidx.compose.ui.semantics.semantics
import com.esuiss.ui.components.Avatar
import com.esuiss.ui.components.AvatarFallback

@Composable
fun AvatarFallbackOnly() {
    Row {
        Avatar(
            modifier = Modifier.semantics { contentDescription = "Alan Turing" },
            fallback = { AvatarFallback("AT") },
        )
    }
}

Sizes

The sm, default, lg and xl sizes.

iOS
Avatar (sizes) on iOS in light modeAvatar (sizes) on iOS in dark mode
import { View } from "react-native"
import { Avatar, AvatarFallback, AvatarImage } from "@/components/ui/avatar"
import { Text } from "@/components/ui/text"

export function AvatarSizesExample() {
  return (
    <View className="flex-row items-center gap-4">
      {(["sm", "default", "lg", "xl"] as const).map((size) => (
        <Avatar key={size} size={size}>
          <AvatarImage
            alt="Ada Lovelace"
            source={{ uri: "https://i.pravatar.cc/150?img=5" }}
          />
          <AvatarFallback>
            <Text>AL</Text>
          </AvatarFallback>
        </Avatar>
      ))}
    </View>
  )
}
import EsuissUI
import SwiftUI

struct AvatarSizesExample: View {
  var body: some View {
    HStack(spacing: 16) {
      ForEach(AvatarSize.allCases, id: \.self) { size in
        Avatar(url: URL(string: "https://i.pravatar.cc/150?img=5"), initials: "AL", size: size)
          .accessibilityLabel(Text("Ada Lovelace"))
      }
    }
  }
}
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Row
import androidx.compose.runtime.Composable
import androidx.compose.runtime.remember
import androidx.compose.ui.Alignment
import androidx.compose.ui.graphics.Brush
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.graphics.painter.BrushPainter
import androidx.compose.ui.semantics.contentDescription
import androidx.compose.ui.unit.dp
import com.esuiss.ui.components.Avatar
import com.esuiss.ui.components.AvatarFallback
import com.esuiss.ui.components.AvatarSize
import com.esuiss.ui.theme.Palette

class AvatarPerson(val name: String, val initials: String, val tones: @Composable () -> List<Color>)

val avatarPeople = listOf(
    AvatarPerson("Ada Lovelace", "AL") { listOf(Palette.pink500, Palette.purple500) },
    AvatarPerson("Alan Turing", "AT") { listOf(Palette.teal500, Palette.blue500) },
    AvatarPerson("Grace Hopper", "GH") { listOf(Palette.orange500, Palette.red500) },
)

@Composable
fun AvatarPhoto(person: AvatarPerson, size: AvatarSize = AvatarSize.Default, badge: (@Composable () -> Unit)? = null) {
    val tones = person.tones()
    val photo = remember(tones) { BrushPainter(Brush.linearGradient(tones)) }
    Avatar(
        size = size,
        image = photo,
        contentDescription = person.name,
        badge = badge,
        fallback = { AvatarFallback(person.initials) },
    )
}

@Composable
fun AvatarSizes() {
    Row(horizontalArrangement = Arrangement.spacedBy(16.dp), verticalAlignment = Alignment.CenterVertically) {
        AvatarSize.entries.forEach { size -> AvatarPhoto(avatarPeople[0], size) }
    }
}

Group

Overlapping avatars in an AvatarGroup with a count.

iOS
Avatar (group) on iOS in light modeAvatar (group) on iOS in dark mode
import { Avatar, AvatarFallback, AvatarGroup, AvatarGroupCount, AvatarImage } from "@/components/ui/avatar"
import { Text } from "@/components/ui/text"

const people = [
  {
    name: "Ada Lovelace",
    initials: "AL",
    uri: "https://i.pravatar.cc/150?img=5",
  },
  {
    name: "Alan Turing",
    initials: "AT",
    uri: "https://i.pravatar.cc/150?img=12",
  },
  {
    name: "Grace Hopper",
    initials: "GH",
    uri: "https://i.pravatar.cc/150?img=47",
  },
]

export function AvatarGroupExample() {
  return (
    <AvatarGroup>
      {people.map((person) => (
        <Avatar key={person.name}>
          <AvatarImage alt={person.name} source={{ uri: person.uri }} />
          <AvatarFallback>
            <Text>{person.initials}</Text>
          </AvatarFallback>
        </Avatar>
      ))}
      <AvatarGroupCount accessibilityLabel="4 more">
        <Text>+4</Text>
      </AvatarGroupCount>
    </AvatarGroup>
  )
}
import EsuissUI
import SwiftUI

struct AvatarGroupExample: View {
  var body: some View {
    AvatarGroup {
      ForEach(avatarPeople, id: \.name) { person in
        Avatar(url: URL(string: person.uri), initials: person.initials)
          .accessibilityLabel(Text(verbatim: person.name))
      }
      AvatarGroupCount("+4")
        .accessibilityLabel(Text("4 more"))
    }
  }
}

struct AvatarPerson {
  let name: String
  let initials: String
  let uri: String
}

let avatarPeople = [
  AvatarPerson(name: "Ada Lovelace", initials: "AL", uri: "https://i.pravatar.cc/150?img=5"),
  AvatarPerson(name: "Alan Turing", initials: "AT", uri: "https://i.pravatar.cc/150?img=12"),
  AvatarPerson(name: "Grace Hopper", initials: "GH", uri: "https://i.pravatar.cc/150?img=47"),
]
import androidx.compose.foundation.layout.Row
import androidx.compose.runtime.Composable
import androidx.compose.runtime.remember
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Brush
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.graphics.painter.BrushPainter
import androidx.compose.ui.semantics.contentDescription
import androidx.compose.ui.semantics.semantics
import com.esuiss.ui.components.Avatar
import com.esuiss.ui.components.AvatarFallback
import com.esuiss.ui.components.AvatarGroup
import com.esuiss.ui.components.AvatarGroupCount
import com.esuiss.ui.components.AvatarSize
import com.esuiss.ui.theme.Palette

class AvatarPerson(val name: String, val initials: String, val tones: @Composable () -> List<Color>)

val avatarPeople = listOf(
    AvatarPerson("Ada Lovelace", "AL") { listOf(Palette.pink500, Palette.purple500) },
    AvatarPerson("Alan Turing", "AT") { listOf(Palette.teal500, Palette.blue500) },
    AvatarPerson("Grace Hopper", "GH") { listOf(Palette.orange500, Palette.red500) },
)

@Composable
fun AvatarPhoto(person: AvatarPerson, size: AvatarSize = AvatarSize.Default, badge: (@Composable () -> Unit)? = null) {
    val tones = person.tones()
    val photo = remember(tones) { BrushPainter(Brush.linearGradient(tones)) }
    Avatar(
        size = size,
        image = photo,
        contentDescription = person.name,
        badge = badge,
        fallback = { AvatarFallback(person.initials) },
    )
}

@Composable
fun AvatarGroupStory() {
    Row {
        AvatarGroup {
            avatarPeople.forEach { person -> AvatarPhoto(person) }
            AvatarGroupCount("+4", Modifier.semantics { contentDescription = "4 more" })
        }
    }
}

With badge

A check badge at each size.

iOS
Avatar (with badge) on iOS in light modeAvatar (with badge) on iOS in dark mode
import { CheckIcon } from "phosphor-react-native"
import { View } from "react-native"
import { Avatar, AvatarBadge, AvatarFallback, AvatarImage } from "@/components/ui/avatar"
import { Icon } from "@/components/ui/icon"
import { Text } from "@/components/ui/text"

export function AvatarWithBadgeExample() {
  return (
    <View className="flex-row items-center gap-4">
      {(["sm", "default", "lg", "xl"] as const).map((size) => (
        <Avatar key={size} size={size}>
          <AvatarImage
            alt="Alan Turing"
            source={{ uri: "https://i.pravatar.cc/150?img=12" }}
          />
          <AvatarFallback>
            <Text>AT</Text>
          </AvatarFallback>
          <AvatarBadge>
            <Icon as={CheckIcon} weight="bold" />
          </AvatarBadge>
        </Avatar>
      ))}
    </View>
  )
}
import EsuissUI
import PhosphorSwift
import SwiftUI

struct AvatarWithBadgeExample: View {
  var body: some View {
    HStack(spacing: 16) {
      ForEach(AvatarSize.allCases, id: \.self) { size in
        Avatar(size: size) {
          AvatarFallback("AT")
          AvatarImage(url: URL(string: "https://i.pravatar.cc/150?img=12"))
          AvatarBadge(icon: Ph.check.bold)
        }
        .accessibilityLabel(Text("Alan Turing"))
      }
    }
  }
}
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Row
import androidx.compose.runtime.Composable
import androidx.compose.runtime.remember
import androidx.compose.ui.Alignment
import androidx.compose.ui.graphics.Brush
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.graphics.painter.BrushPainter
import androidx.compose.ui.semantics.contentDescription
import androidx.compose.ui.unit.dp
import com.adamglin.PhosphorIcons
import com.adamglin.phosphoricons.Bold
import com.adamglin.phosphoricons.bold.Check
import com.esuiss.ui.components.Avatar
import com.esuiss.ui.components.AvatarBadge
import com.esuiss.ui.components.AvatarFallback
import com.esuiss.ui.components.AvatarSize
import com.esuiss.ui.components.Icon
import com.esuiss.ui.theme.Palette

class AvatarPerson(val name: String, val initials: String, val tones: @Composable () -> List<Color>)

val avatarPeople = listOf(
    AvatarPerson("Ada Lovelace", "AL") { listOf(Palette.pink500, Palette.purple500) },
    AvatarPerson("Alan Turing", "AT") { listOf(Palette.teal500, Palette.blue500) },
    AvatarPerson("Grace Hopper", "GH") { listOf(Palette.orange500, Palette.red500) },
)

@Composable
fun AvatarPhoto(person: AvatarPerson, size: AvatarSize = AvatarSize.Default, badge: (@Composable () -> Unit)? = null) {
    val tones = person.tones()
    val photo = remember(tones) { BrushPainter(Brush.linearGradient(tones)) }
    Avatar(
        size = size,
        image = photo,
        contentDescription = person.name,
        badge = badge,
        fallback = { AvatarFallback(person.initials) },
    )
}

@Composable
fun AvatarWithBadge() {
    Row(horizontalArrangement = Arrangement.spacedBy(16.dp), verticalAlignment = Alignment.CenterVertically) {
        AvatarSize.entries.forEach { size ->
            AvatarPhoto(avatarPeople[1], size) {
                AvatarBadge {
                    Icon(PhosphorIcons.Bold.Check, contentDescription = null)
                }
            }
        }
    }
}

API Reference

01

Avatar

Round container that sets the size.

PropTypeDefaultDescription
sizeAvatarSize"default"sm, default, lg or xl.

Also accepts the props of React.ComponentProps<typeof AvatarPrimitive.Root>.

02

AvatarImage

Image that appears once it has loaded.

Also accepts the props of React.ComponentProps<typeof AvatarPrimitive.Image>.

03

AvatarFallback

Initials or icon shown while the image is missing.

Also accepts the props of React.ComponentProps<typeof AvatarPrimitive.Fallback>.

04

AvatarBadge

Status dot in the bottom-end corner.

Also accepts the props of React.ComponentProps<typeof View>, React.RefAttributes<View>.

05

AvatarGroup

Row that overlaps its avatars.

Also accepts the props of React.ComponentProps<typeof View>, React.RefAttributes<View>.

06

AvatarGroupCount

Round counter for the remaining items in a group.

PropTypeDefaultDescription
sizeAvatarSize"default"Matches the size of the avatars in the group.

Also accepts the props of React.ComponentProps<typeof View>, React.RefAttributes<View>.

Accessibility

  • AvatarImage uses alt as its accessibilityLabel.
  • The image is hidden from screen readers until it has loaded.
  • The badge has no label; describe the status in nearby text if it matters.

Notes

  • Uses bg-muted-foreground, bg-primary, bg-muted and border-background tokens; the fallback is softer in dark mode.
  • Light and dark follow the system appearance.
iOS
Avatar on iOS in light modeAvatar on iOS in dark mode
import { Avatar, AvatarFallback, AvatarImage } from "@/components/ui/avatar"
import { Text } from "@/components/ui/text"

export function AvatarExample() {
  return (
    <Avatar>
      <AvatarImage
        alt="Ada Lovelace"
        source={{ uri: "https://i.pravatar.cc/150?img=5" }}
      />
      <AvatarFallback>
        <Text>AL</Text>
      </AvatarFallback>
    </Avatar>
  )
}
import EsuissUI
import SwiftUI

struct AvatarExample: View {
  var body: some View {
    Avatar(url: URL(string: "https://i.pravatar.cc/150?img=5"), initials: "AL")
      .accessibilityLabel(Text("Ada Lovelace"))
  }
}
import androidx.compose.foundation.layout.Row
import androidx.compose.runtime.Composable
import androidx.compose.runtime.remember
import androidx.compose.ui.graphics.Brush
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.graphics.painter.BrushPainter
import androidx.compose.ui.semantics.contentDescription
import com.esuiss.ui.components.Avatar
import com.esuiss.ui.components.AvatarFallback
import com.esuiss.ui.components.AvatarSize
import com.esuiss.ui.theme.Palette

class AvatarPerson(val name: String, val initials: String, val tones: @Composable () -> List<Color>)

val avatarPeople = listOf(
    AvatarPerson("Ada Lovelace", "AL") { listOf(Palette.pink500, Palette.purple500) },
    AvatarPerson("Alan Turing", "AT") { listOf(Palette.teal500, Palette.blue500) },
    AvatarPerson("Grace Hopper", "GH") { listOf(Palette.orange500, Palette.red500) },
)

@Composable
fun AvatarPhoto(person: AvatarPerson, size: AvatarSize = AvatarSize.Default, badge: (@Composable () -> Unit)? = null) {
    val tones = person.tones()
    val photo = remember(tones) { BrushPainter(Brush.linearGradient(tones)) }
    Avatar(
        size = size,
        image = photo,
        contentDescription = person.name,
        badge = badge,
        fallback = { AvatarFallback(person.initials) },
    )
}

@Composable
fun AvatarDefault() {
    Row {
        AvatarPhoto(avatarPeople[0])
    }
}
import { Avatar, AvatarFallback, AvatarImage } from "@/components/ui/avatar"

const people = [
  {
    name: "Emma Wilson",
    initials: "EW",
    src: "https://i.pravatar.cc/128?img=47",
  },
  {
    name: "Liam Carter",
    initials: "LC",
    src: "https://i.pravatar.cc/128?img=12",
  },
  {
    name: "Sofia Martinez",
    initials: "SM",
    src: "https://i.pravatar.cc/128?img=32",
  },
] as const

export default function AvatarDemo() {
  return (
    <Avatar>
      <AvatarImage src={people[0].src} alt={people[0].name} />
      <AvatarFallback>{people[0].initials}</AvatarFallback>
    </Avatar>
  )
}
components/ui/avatar.tsx
"use client"

import { Avatar as AvatarPrimitive } from "@base-ui/react/avatar"
import type * as React from "react"
import { cn } from "@/lib/utils"

function Avatar({
  className,
  size = "default",
  ...props
}: AvatarPrimitive.Root.Props & {
  size?: "default" | "sm" | "lg" | "xl"
}) {
  return (
    <AvatarPrimitive.Root
      data-slot="avatar"
import { Avatar, AvatarFallback } from "@/components/ui/avatar"

const people = [
  {
    name: "Emma Wilson",
    initials: "EW",
    src: "https://i.pravatar.cc/128?img=47",
  },
  {
    name: "Liam Carter",
    initials: "LC",
    src: "https://i.pravatar.cc/128?img=12",
  },
  {
    name: "Sofia Martinez",
    initials: "SM",
    src: "https://i.pravatar.cc/128?img=32",
  },
] as const

export default function AvatarFallbackSizes() {
  return (
    <div className="flex items-center gap-3">
      {(["sm", "default", "lg", "xl"] as const).map((size) => (
        <Avatar key={size} size={size}>
          <AvatarFallback>{people[0].initials}</AvatarFallback>
        </Avatar>
      ))}
    </div>
  )
}
import { Avatar, AvatarFallback } from "@/components/ui/avatar"

export default function AvatarFallbackExample() {
  return (
    <Avatar>
      <AvatarFallback>LC</AvatarFallback>
    </Avatar>
  )
}
import { UserIcon } from "@phosphor-icons/react"
import { Avatar, AvatarFallback } from "@/components/ui/avatar"

export default function AvatarPlaceholder() {
  return (
    <div className="flex items-center gap-3">
      {(["sm", "default", "lg", "xl"] as const).map((size) => (
        <Avatar key={size} size={size}>
          <AvatarFallback>
            <UserIcon className="fill-current" />
          </AvatarFallback>
        </Avatar>
      ))}
    </div>
  )
}
import { Avatar, AvatarFallback, AvatarImage } from "@/components/ui/avatar"

const people = [
  {
    name: "Emma Wilson",
    initials: "EW",
    src: "https://i.pravatar.cc/128?img=47",
  },
  {
    name: "Liam Carter",
    initials: "LC",
    src: "https://i.pravatar.cc/128?img=12",
  },
  {
    name: "Sofia Martinez",
    initials: "SM",
    src: "https://i.pravatar.cc/128?img=32",
  },
] as const

export default function AvatarSizes() {
  return (
    <div className="flex items-center gap-3">
      {(["sm", "default", "lg", "xl"] as const).map((size) => (
        <Avatar key={size} size={size}>
          <AvatarImage src={people[1].src} alt={people[1].name} />
          <AvatarFallback>{people[1].initials}</AvatarFallback>
        </Avatar>
      ))}
    </div>
  )
}
import { CheckIcon } from "@phosphor-icons/react"
import {
  Avatar,
  AvatarBadge,
  AvatarFallback,
  AvatarImage,
} from "@/components/ui/avatar"

const people = [
  {
    name: "Emma Wilson",
    initials: "EW",
    src: "https://i.pravatar.cc/128?img=47",
  },
  {
    name: "Liam Carter",
    initials: "LC",
    src: "https://i.pravatar.cc/128?img=12",
  },
  {
    name: "Sofia Martinez",
    initials: "SM",
    src: "https://i.pravatar.cc/128?img=32",
  },
] as const

export default function AvatarWithBadge() {
  return (
    <div className="flex items-center gap-4">
      {(["sm", "default", "lg", "xl"] as const).map((size) => (
        <Avatar key={size} size={size}>
          <AvatarImage src={people[2].src} alt={people[2].name} />
          <AvatarFallback>{people[2].initials}</AvatarFallback>
          <AvatarBadge className="bg-green-500">
            <CheckIcon />
          </AvatarBadge>
        </Avatar>
      ))}
    </div>
  )
}
import {
  Avatar,
  AvatarFallback,
  AvatarGroup,
  AvatarGroupCount,
  AvatarImage,
} from "@/components/ui/avatar"

const people = [
  {
    name: "Emma Wilson",
    initials: "EW",
    src: "https://i.pravatar.cc/128?img=47",
  },
  {
    name: "Liam Carter",
    initials: "LC",
    src: "https://i.pravatar.cc/128?img=12",
  },
  {
    name: "Sofia Martinez",
    initials: "SM",
    src: "https://i.pravatar.cc/128?img=32",
  },
] as const

export default function AvatarGroupExample() {
  return (
    <AvatarGroup>
      {people.map((person) => (
        <Avatar key={person.name}>
          <AvatarImage src={person.src} alt={person.name} />
          <AvatarFallback>{person.initials}</AvatarFallback>
        </Avatar>
      ))}
      <AvatarGroupCount>+4</AvatarGroupCount>
    </AvatarGroup>
  )
}
import { PlusIcon } from "@phosphor-icons/react"
import {
  Avatar,
  AvatarFallback,
  AvatarGroup,
  AvatarGroupCount,
  AvatarImage,
} from "@/components/ui/avatar"

const people = [
  {
    name: "Emma Wilson",
    initials: "EW",
    src: "https://i.pravatar.cc/128?img=47",
  },
  {
    name: "Liam Carter",
    initials: "LC",
    src: "https://i.pravatar.cc/128?img=12",
  },
  {
    name: "Sofia Martinez",
    initials: "SM",
    src: "https://i.pravatar.cc/128?img=32",
  },
] as const

export default function AvatarGroupWithIconCount() {
  return (
    <AvatarGroup>
      {people.map((person) => (
        <Avatar key={person.name} size="lg">
          <AvatarImage src={person.src} alt={person.name} />
          <AvatarFallback>{person.initials}</AvatarFallback>
        </Avatar>
      ))}
      <AvatarGroupCount>
        <PlusIcon />
      </AvatarGroupCount>
    </AvatarGroup>
  )
}
uniwind/components/ui/avatar.tsx
import { cn } from "cn"
import * as React from "react"
import { View } from "react-native"
import * as AvatarPrimitive from "@/components/primitives/avatar"
import { resolveClassName } from "@/components/primitives/use-render"
import { IconClassContext } from "@/components/ui/icon"
import { Text, TextClassContext } from "@/components/ui/text"

type AvatarSize = "default" | "sm" | "lg" | "xl"

const AvatarSizeContext = React.createContext<AvatarSize>("default")

const AvatarGroupItemContext = React.createContext<number | null>(null)

const ROOT_SIZE: Record<AvatarSize, string> = {
  sm: "size-6",
nativewind/components/ui/avatar.tsx
import { cn } from "cn"
import * as React from "react"
import { View } from "react-native"
import * as AvatarPrimitive from "@/components/primitives/avatar"
import { resolveClassName } from "@/components/primitives/use-render"
import { IconClassContext } from "@/components/ui/icon"
import { Text, TextClassContext } from "@/components/ui/text"

type AvatarSize = "default" | "sm" | "lg" | "xl"

const AvatarSizeContext = React.createContext<AvatarSize>("default")

const AvatarGroupItemContext = React.createContext<number | null>(null)

const ROOT_SIZE: Record<AvatarSize, string> = {
  sm: "size-6",
swift/Components/Avatar.swift
import SwiftUI

public enum AvatarSize: CaseIterable, Sendable {
  case sm, `default`, lg, xl

  var dimension: CGFloat {
    switch self {
    case .sm: 24
    case .default: 32
    case .lg: 40
    case .xl: 64
    }
  }

  var overlap: CGFloat {
    self == .xl ? 16 : 8
stylesheet/components/ui/avatar.tsx
import * as React from "react"
import { StyleSheet, View } from "react-native"
import * as AvatarPrimitive from "@/components/primitives/avatar"
import { IconSizeContext } from "@/components/ui/icon"
import { Text, TextStyleContext } from "@/components/ui/text"
import { fontSize, radius, useTheme } from "@/components/ui/theme"

type AvatarSize = "default" | "sm" | "lg" | "xl"

const AvatarSizeContext = React.createContext<AvatarSize>("default")

const AvatarGroupItemContext = React.createContext<number | null>(null)

const ROOT_SIZE: Record<AvatarSize, number> = {
  sm: 24,
  default: 32,