---

React Native User Avatar

A bare-bones user avatar component that falls back to the user's initials on a deterministic colored background. Works on iOS, Android, and Web, ships with TypeScript types, and has no runtime polyfills — it uses the global fetch/AbortController available in modern React Native.

Inspired by react-user-avatar and ported to React Native.

iOS Screenshot	Android Screenshot

Installation

npm install react-native-user-avatar
# or
yarn add react-native-user-avatar

react and react-native are peer dependencies — this library uses whatever version your app already has installed. No extra native setup is required; it is a pure JavaScript component.

Usage

The fallback avatar's color can be set with the bgColor prop, or customized by passing an array of bgColors. The same name always maps to the same color.

import UserAvatar from 'react-native-user-avatar';
import { View } from 'react-native';

export default function App() {
  return (
    <View>
      <UserAvatar size={100} name="Avishay Bar" />
      <UserAvatar
        size={100}
        name="Avishay Bar"
        src="https://dummyimage.com/100x100/000/fff"
      />
      <UserAvatar size={50} name="John Doe" bgColors={['#ccc', '#fafafa', '#ccaabb']} />
      <UserAvatar size={50} name="John Doe" />
      <UserAvatar size={50} name="Jane Doe" bgColor="#000" />
    </View>
  );
}

TypeScript

Types are bundled — no @types/* package is needed. You can import the prop type:

import UserAvatar, { UserAvatarProps } from 'react-native-user-avatar';

Props

Attribute	Type	Default	Description
name	string	'John Doe'	Name used to generate the initials.
src	string	undefined	Remote image URL. Shown when it resolves to a valid image.
bgColor	string	undefined	Force a specific background color for the initials.
bgColors	string[]	built-in palette	Palette the deterministic background color is picked from.
textColor	string	'#fff'	Color of the initials text.
size	number	32	Avatar width/height and initials font scale.
imageStyle	StyleProp<ImageStyle>	undefined	Extra style applied to the image.
textStyle	StyleProp<TextStyle>	undefined	Extra style applied to the initials text.
style	StyleProp<ViewStyle>	undefined	Extra style applied to the outer container.
borderRadius	number	size / 2	Border radius of the avatar (defaults to a circle).
component	ReactNode	undefined	Render a custom element instead of initials/image.
noUpperCase	boolean	false	Keep initials in their original case.
ignoreContentType	boolean	false	Skip the image/* content-type check on src (e.g. for S3 URLs without an extension).

Web & Expo

The component works in Expo and react-native-web projects without extra configuration. See the Example/ app for a runnable Expo demo (iOS, Android, and Web).

Migrating from v1 to v2

v2 is a modernization release. It is a drop-in replacement for most apps, but note:

• react/react-native are now peer dependencies. They are no longer bundled as hard dependencies, so your app's versions are always used.
• Polyfills removed. abortcontroller-polyfill and node-fetch are gone; the component relies on the global fetch/AbortController (available in RN ≥ 0.60).
• textStyle now works reliably, including after the initial render (#117).
• Fewer console warnings — no defaultProps deprecation warning, and aborted image fetches no longer log.
• TypeScript types are correct and bundled (#114, #129).
• Initials are now capped at 3 characters.

Contributing

Contributions are welcome — see CONTRIBUTING.md. Working in this repo with an AI assistant? Start from CLAUDE.md.

Credits

@wbinnssmith for creating react-user-avatar.

License

MIT