Avatar

Avatars represent a user or entity with an image, icon, or text initials.

Usage

Open on Snack ↗

import { Avatar } from '@onlynative/components'
import { ThemeProvider } from '@onlynative/core'
import { SafeAreaProvider } from 'react-native-safe-area-context'
import { View } from 'react-native'

export default function App() {
  return (
    <SafeAreaProvider>
      <ThemeProvider>
        <View style={{ flex: 1, flexDirection: 'row', alignItems: 'center', justifyContent: 'center', gap: 16 }}>
          <Avatar imageUri="https://i.pravatar.cc/80" />
          <Avatar icon="account" />
          <Avatar label="JD" />
        </View>
      </ThemeProvider>
    </SafeAreaProvider>
  )
}

Content priority

The avatar renders the first available content in this order:

1. imageUri — displays the image
2. icon — displays a MaterialCommunityIcons icon (defaults to account)
3. label — displays up to 2 uppercase initials

Sizes

Size	Use case
xSmall	Inline mentions, dense lists
small	List items, compact layouts
medium	Default — profile cards, headers
large	Profile screens, detail views
xLarge	Hero sections, onboarding

Open on Snack ↗

import { Avatar } from '@onlynative/components'
import { ThemeProvider } from '@onlynative/core'
import { SafeAreaProvider } from 'react-native-safe-area-context'
import { View } from 'react-native'

export default function App() {
  return (
    <SafeAreaProvider>
      <ThemeProvider>
        <View style={{ flex: 1, flexDirection: 'row', alignItems: 'center', justifyContent: 'center', gap: 16 }}>
          <Avatar label="AB" size="xSmall" />
          <Avatar label="AB" size="small" />
          <Avatar label="AB" size="medium" />
          <Avatar label="AB" size="large" />
          <Avatar label="AB" size="xLarge" />
        </View>
      </ThemeProvider>
    </SafeAreaProvider>
  )
}

Interactive Avatar

When onPress is provided, the avatar renders as a Pressable with automatic state-layer feedback (hover and press):

Open on Snack ↗

import { Avatar } from '@onlynative/components'
import { ThemeProvider } from '@onlynative/core'
import { SafeAreaProvider } from 'react-native-safe-area-context'
import { Alert, View } from 'react-native'

export default function App() {
  return (
    <SafeAreaProvider>
      <ThemeProvider>
        <View style={{ flex: 1, alignItems: 'center', justifyContent: 'center' }}>
          <Avatar
            imageUri="https://i.pravatar.cc/80"
            onPress={() => Alert.alert('Tapped')}
            accessibilityLabel="Open profile"
          />
        </View>
      </ThemeProvider>
    </SafeAreaProvider>
  )
}

Custom colors

Override the container and content colors:

Open on Snack ↗

import { Avatar } from '@onlynative/components'
import { ThemeProvider } from '@onlynative/core'
import { SafeAreaProvider } from 'react-native-safe-area-context'
import { View } from 'react-native'

export default function App() {
  return (
    <SafeAreaProvider>
      <ThemeProvider>
        <View style={{ flex: 1, alignItems: 'center', justifyContent: 'center' }}>
          <Avatar label="AB" containerColor="#E8DEF8" contentColor="#1D1B20" />
        </View>
      </ThemeProvider>
    </SafeAreaProvider>
  )
}

Props

Prop	Type	Default	Required	Description
imageUri	string	-	No	URI of the image to display. Takes priority over `icon` and `label`.
icon	IconSource	-	No	Icon to display. Accepts a string name (resolved via the theme's `iconResolver`, defaulting to `MaterialCommunityIcons`), a pre-rendered element, or a render function that receives `{ size, color }`. Takes priority over `label` when `imageUri` is not set.
label	string	-	No	Text initials to display (1–2 characters recommended). Shown when `imageUri` and `icon` are not set.
size	enum	medium	No	Size of the avatar.
containerColor	string	-	No	Override the container (background) color. State-layer colors (hover, press) are derived automatically when `onPress` is set.
contentColor	string	-	No	Override the content (icon / initials) color.
style	StyleProp<ViewStyle>	-	No	Custom style applied to the root container.
onPress	() => void	-	No	When provided, the avatar becomes interactive (Pressable).
accessibilityLabel	string	-	No	Required when `onPress` is provided — labels the button for screen readers.