suiss/uim · React Native Component
Avatar
A round image for a person or entity, with initials or an icon as a fallback.
Avatar is an open-source mobile component from suiss/uim for React Native and Expo, with SwiftUI and Jetpack Compose versions built from the same design tokens. The @esuiss/uim CLI copies its source into your project, so you own the code.
iOS
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.EsuissTheme
class AvatarPerson(val name: String, val initials: String, val tones: @Composable () -> List<Color>)
val avatarPeople = listOf(
AvatarPerson("Ada Lovelace", "AL") { listOf(EsuissTheme.colors.pink, EsuissTheme.colors.purple) },
AvatarPerson("Alan Turing", "AT") { listOf(EsuissTheme.colors.teal, EsuissTheme.colors.blue) },
AvatarPerson("Grace Hopper", "GH") { listOf(EsuissTheme.colors.orange, EsuissTheme.colors.red) },
)
@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])
}
}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 @esuiss/uim@latest add avatar$ pnpm dlx @esuiss/uim@latest add avatar --platform swift$ pnpm dlx @esuiss/uim@latest add avatar --platform kotlinThe CLI also adds what it builds on: Icon, Text.
Manual
- Install the dependencies:
npx expo install cn-
Add the pieces it builds on: Icon, Text, and the primitives
components/primitives/avatar.tsx,components/primitives/use-render.tsx. -
Copy the source into
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",- Update the import paths to match your project.
- Install the dependencies:
npx expo install cn-
Add the pieces it builds on: Icon, Text, and the primitives
components/primitives/avatar.tsx,components/primitives/use-render.tsx. -
Copy the source into
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",- Update the import paths to match your project.
-
Add the pieces it builds on: Icon, Text, and the primitives
components/primitives/avatar.tsx,components/primitives/use-render.tsx. -
Copy the source into
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,- Update the import paths to match your project.
-
Target iOS 17 or later.
-
Copy the theme files every view uses:
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
}import SwiftUI
extension Color {
public static let surface = Color.adaptive(light: .init(0xFFFFFF), dark: .init(0x000000))
public static let surfaceSecondary = Color.adaptive(light: .init(0xF5F5F7), dark: .init(0x161617))
public static let surfaceTertiary = Color.adaptive(light: .init(0xE8E8ED), dark: .init(0x2C2C2E))
public static let surfaceRaised = Color.adaptive(light: .init(0xFFFFFF), dark: .init(0x1D1D1F))
public static let label = Color.adaptive(light: .init(0x1D1D1F), dark: .init(0xF5F5F7))
public static let labelSecondary = Color.adaptive(light: .init(0x6E6E73), dark: .init(0xA1A1A6))
public static let labelTertiary = Color.adaptive(light: .init(0x86868B), dark: .init(0x86868B))
public static let labelQuaternary = Color.adaptive(light: .init(0xD2D2D7), dark: .init(0x424245))
public static let control = Color.adaptive(light: .init(0x000000, 0.04), dark: .init(0xFFFFFF, 0.1))
public static let controlPressed = Color.adaptive(light: .init(0x000000, 0.12), dark: .init(0xFFFFFF, 0.22))
public static let controlSelected = Color.adaptive(light: .init(0x1D1D1F), dark: .init(0xF5F5F7))
public static let controlDisabled = Color.adaptive(light: .init(0x000000, 0.03), dark: .init(0xFFFFFF, 0.05))
public static let onControlSelected = Color.adaptive(light: .init(0xFFFFFF), dark: .init(0x000000))- Copy the source and every file it uses:
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 : 8import 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
}
}- Add the files to your app target.
- Set
minSdkto 24 or higher and add the dependencies:
implementation(platform("androidx.compose:compose-bom:2026.09.00"))
implementation("androidx.compose.foundation:foundation")
implementation("androidx.compose.ui:ui")- Copy the theme files every view uses:
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.DpOffsetpackage 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 surface: Color,
val surfaceSecondary: Color,
val surfaceTertiary: Color,
val surfaceRaised: Color,
val label: Color,
val labelSecondary: Color,
val labelTertiary: Color,
val labelQuaternary: Color,- Copy the source and every file it uses:
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.Modifierpackage 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 }- Update the
com.esuiss.uipackage 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
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
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.EsuissTheme
class AvatarPerson(val name: String, val initials: String, val tones: @Composable () -> List<Color>)
val avatarPeople = listOf(
AvatarPerson("Ada Lovelace", "AL") { listOf(EsuissTheme.colors.pink, EsuissTheme.colors.purple) },
AvatarPerson("Alan Turing", "AT") { listOf(EsuissTheme.colors.teal, EsuissTheme.colors.blue) },
AvatarPerson("Grace Hopper", "GH") { listOf(EsuissTheme.colors.orange, EsuissTheme.colors.red) },
)
@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
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.EsuissTheme
class AvatarPerson(val name: String, val initials: String, val tones: @Composable () -> List<Color>)
val avatarPeople = listOf(
AvatarPerson("Ada Lovelace", "AL") { listOf(EsuissTheme.colors.pink, EsuissTheme.colors.purple) },
AvatarPerson("Alan Turing", "AT") { listOf(EsuissTheme.colors.teal, EsuissTheme.colors.blue) },
AvatarPerson("Grace Hopper", "GH") { listOf(EsuissTheme.colors.orange, EsuissTheme.colors.red) },
)
@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
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.EsuissTheme
class AvatarPerson(val name: String, val initials: String, val tones: @Composable () -> List<Color>)
val avatarPeople = listOf(
AvatarPerson("Ada Lovelace", "AL") { listOf(EsuissTheme.colors.pink, EsuissTheme.colors.purple) },
AvatarPerson("Alan Turing", "AT") { listOf(EsuissTheme.colors.teal, EsuissTheme.colors.blue) },
AvatarPerson("Grace Hopper", "GH") { listOf(EsuissTheme.colors.orange, EsuissTheme.colors.red) },
)
@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
Avatar
Round container that sets the size.
Extends
React.ComponentProps<typeof AvatarPrimitive.Root>PropTypeDefault
- About
sm,default,lgorxl.- Type
AvatarSize- Default
- "default"
AvatarImage
Image that appears once it has loaded.
Extends
React.ComponentProps<typeof AvatarPrimitive.Image>AvatarFallback
Initials or icon shown while the image is missing.
Extends
React.ComponentProps<typeof AvatarPrimitive.Fallback>AvatarBadge
Status dot in the bottom-end corner.
Extends
React.ComponentProps<typeof View>React.RefAttributes<View>AvatarGroup
Row that overlaps its avatars.
Extends
React.ComponentProps<typeof View>React.RefAttributes<View>AvatarGroupCount
Round counter for the remaining items in a group.
Extends
React.ComponentProps<typeof View>React.RefAttributes<View>PropTypeDefault
- About
- Matches the size of the avatars in the group.
- Type
AvatarSize- Default
- "default"
Accessibility
AvatarImageusesaltas itsaccessibilityLabel.- 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-label-secondary,bg-accent,bg-surface-secondaryandborder-surfacetokens; the fallback is softer in dark mode. - Light and dark follow the system appearance.