Create Image Avatars with text based fallbacks for react

May 17, 2021
Create Image Avatars with text based fallbacks for react

React Avatar

Create Image Avatars with text based fallbacks.

View Demo View Github

Features ✨

  1. Ability to render image avatar or text avatar as circle or square.
  2. Ability to render text based fallbacks for images for the time they take to load or error.
  3. Renders text based avatars and backgrounds based on text passed in.
  4. Autoscales text if it doesn't fit the container width.
  5. Automatically determines readable text color depending on background.
  6. Exposes a hook to use/generate gravatar for a user.
  7. Exposes a context so you can configure avatar components across your application.


npm install @agney/react-avatar # OR yarn add @agney/react-avatar

Requires React v16.8 or above and Styled Components v4 or above.


import React from "react"; import { Avatar } from "@agney/react-avatar"; const App = () => { return ( <Avatar src="https://gravatar.com/avatar/7c4ff521986b4ff8d29440beec01972d?s=400&d=robohash&r=x" text="CM" /> ); } export default App;


DescriptionDefault Value
srcSource of image to be displayed
textText to be displayed as fallback
imageAltAlt tag for image'' - decorative
shapeshape of avatar. options: 'circle''square'
htmlWidthwidth of image element and text fallback.100%
htmlHeightheight of image element and text fallbacksame as htmlWidth
backgroundsArray of background colors['#3c40c6','#ffa801','#485460','#0be881','#f53b57']
bgColorbackground color for specific text fallback.picks random from backgrounds, this changes according to text prop passed in.
textColortext color for specific text fallbackreadable dark or light color depending on background.
textProcessorfunction to process visible text inside the avatar. Original text will be used for hashing so even ones with same initials inside avatar can have different backgrounds.(text) => text
classNameclassName on the wrapper. can be used for wrapping with CSS-in-JS frameworks

See Storybook for more examples and code snippets.


Package exposes a context in the form of AvatarContext.

import { Avatar, AvatarContext } from '../.'; function App() { const contextValue = React.useMemo(() => ({ backgrounds: ['#000000', '#DD2C00', '#6200EA', '#3F51B5'], // Any props used by Avatar can be used here. }), []); return ( <AvatarContext.Provider> <div style={{ display: 'flex' }}> <Avatar htmlWidth='150px' text="Fallback" backgrounds={['red']} textColor='white' /> <Avatar htmlWidth='150px' text="AJ" /> </div> </AvatarContext.Provider> ) }

Values on the Context Provider are overridden by any props that are on the individual component. Context Provider is not compulsory for usage of Avatar component. Read more about Context API on docs.

useGravatar hook

Gravatars or Globally Recognized Avatars is a free service that allows you to share profile pictures/avatars across different sites and services. react-avatar exposes a hook that makes it easier for you to request and use these gravatars in your application.


import React from "react"; import { Avatar, useGravatar } from "@agney/react-avatar"; const App = () => { const url = useGravatar('[email protected]'); return ( <Avatar src={url} text="CM" /> ); } export default App;


emailEmail of the person for which gravatar is to be fetched
configconfiguration object. following fields are part of this object
config.sizenumber representing height & width of image. 1px up to 2048px80
config.defaultImageIf the image is not available, gravatar defaults to this property. You can provide a custom URL image to default to or one of the alternatives that Gravatar supports.
config.forceDefaultAlways returns the default image if truefalse
config.ratingGravatar allows users to self rate their images. If required pass in a higher rating.g

For a complete list of available options, view Gravatar docs


We use yarn v1 for development.

yarn yarn start # To run example cd example yarn start # Running storybook yarn run storybook

Run tests

yarn test