Need help with react-avatar?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

Sitebase
491 Stars 102 Forks MIT License 378 Commits 13 Opened issues

Description

Universal avatar makes it possible to fetch/generate an avatar based on the information you have about that user.

Services available

!
?

Need anything else?

Contributors list

<Avatar> Build Status npm downloads version npm bundle size (minified + gzip) npm type definitions

Universal avatar makes it possible to fetch/generate an avatar based on the information you have about that user. We use a fallback system that if for example an invalid Facebook ID is used it will try Google, and so on.

React Avatar component preview

For the moment we support following types:

The fallbacks are in the same order as the list above were Facebook has the highest priority.

Demo

Check it live!

Install

Install the component using NPM:

$ npm install react-avatar --save

besides React, react-avatar also has prop-types as peer dependency,

make sure to install it into your project

$ npm install prop-types --save

Or download as ZIP.

Note on usage in Gatsby projects

Users of Gatsby who are experiencing issues with the latest release should install

[email protected]
instead. This is an older version (v3.7.0) release of
react-avatar
that still used
[email protected]
.

If you'd like to use the latest version of

react-avatar
have a look at #187 for a workaround and #187, #181 and #198 for a description of the issue.

Usage

  1. Import Custom Element:

    import Avatar from 'react-avatar';
    
  2. Start using it!

    
    

Some examples:









Manually generating a color:

import Avatar from 'react-avatar';

Configuring React Avatar globally

import Avatar, { ConfigProvider } from 'react-avatar';


    
        ...
        
        ...
    


Options

Avatar

| Attribute | Options | Default | Description | | ------------- | ----------------- | ------- | ------------------------------------------------------------------------------------------------------ | |

className
| string | | Name of the CSS class you want to add to this component alongside the default
sb-avatar
. | |
email
| string | | String of the email address of the user. | |
md5Email
| string | | String of the MD5 hash of email address of the user. | |
facebookId
| string | | | |
twitterHandle
| string | | | |
instagramId
| string | | | |
googleId
| string | | | |
githubHandle
| string | | String of the user's GitHub handle. | |
skypeId
| string | | | |
name
| string | | Will be used to generate avatar based on the initials of the person | |
maxInitials
| number | | Set max nr of characters used for the initials. If maxInitials=2 and the name is Foo Bar Var the initials will be FB | |
initials
| string or function | defaultInitials | Set the initials to show or a function that derives them from the component props, the method should have the signature
fn(name, props)
| |
value
| string | | Show a value as avatar | |
alt
| string |
name
or
value
| The
alt
attribute used on the avatar
img
tag. If not set we will fallback to either
name
or
value
| |
title
| string |
name
or
value
| The
title
attribute used on the avatar
img
tag. If not set we will fallback to either
name
or
value
| |
color
| string | random | Used in combination with
name
and
value
. Give the background a fixed color with a hex like for example #FF0000 | |
fgColor
| string | #FFF | Used in combination with
name
and
value
. Give the text a fixed color with a hex like for example #FF0000 | |
size
| length | 50px | Size of the avatar | |
textSizeRatio
| number | 3 | For text based avatars the size of the text as a fragment of size (size / textSizeRatio) | |
textMarginRatio
| number | .15 | For text based avatars. The size of the minimum margin between the text and the avatar's edge, used to make sure the text will always fit inside the avatar. (calculated as
size * textMarginRatio
) | |
round
| bool or length | false | The amount of
border-radius
to apply to the avatar corners,
true
shows the avatar in a circle. | |
src
| string | | Fallback image to use | |
style
| object | | Style that will be applied on the root element | |
unstyled
| bool | false | Disable all styles | |
onClick
| function | | Mouse click event |

ConfigProvider

| Attribute | Options | Default | Description | | ------------- | ----------------- | ------- | ------------------------------------------------------------------------------------------------------ | |

colors
| array(string) | default colors | A list of color values as strings from which the
getRandomColor
picks one at random. | |
cache
| cache | internal cache | Cache implementation used to track broken img URLs | |
initials
| function | defaultInitials | A function that derives the initials from the component props, the method should have the signature
fn(name, props)
| |
avatarRedirectUrl
| URL |
undefined
| Base URL to a Avatar Redirect instance |

Example

import Avatar, { ConfigProvider } from 'react-avatar';


    
        ...
        
        ...
    


Cache

This class represents the default implementation of the cache used by react-avatar.

Looking to implement more complex custom cache behaviour?

| Attribute | Options | Default | Description | | ------------- | ----------------- | ------- | ------------------------------------------------------------------------------------------------------ | |

cachePrefix
| string |
react-avatar/
| The prefix for
localStorage
keys used by the cache. | |
sourceTTL
| number | 604800000 (7 days) | The amount of time a failed source is kept in cache. (in milliseconds) | |
sourceSize
| number | 20 | The maximum number of failed source entries to keep in cache at any time. |

usage

import Avatar, { Cache, ConfigProvider } from 'react-avatar';

const cache = new Cache({

// Keep cached source failures for up to 7 days
sourceTTL: 7 * 24 * 3600 * 1000,

// Keep a maximum of 20 entries in the source cache
sourceSize: 20

});

// Apply cache globally ... ...

// For specific instances

Avatar Redirect

Avatar Redirect adds support for social networks which require a server-side service to find the correct avatar URL.

Examples of this are:

  • Twitter
  • Instagram

An open Avatar Redirect endpoint is provided at

https://avatar-redirect.appspot.com
. However this endpoint is provided for free and as such an explicit opt-in is required as no guarantees can be made about uptime of this endpoint.

Avatar Redirect is enabled by setting the

avatarRedirectUrl
property on the ConfigProvider context

Development

In order to run it locally you'll need to fetch some dependencies and a basic server setup.

  • Install local dependencies:

    $ npm install
    
  • To test your react-avatar and your changes, start the development server and open

    http://localhost:8000/index.html
    .
    $ npm run dev
    
  • To create a local production build into the

    lib
    and
    es
    folders.
   $ npm run build

Implementing a custom cache

cache
as provided to the
ConfigProvider
should be an object implementing the methods below. The default cache implementation can be found here

| Method | Description | | ------------- | ------------------------------------------------------------------------------------------------------ | |

set(key, value)
| Save
value
at
key
, such that it can be retrieved using
get(key)
. Returns
undefined
| |
get(key)
| Retrieve the value stored at
key
, if the cache does not contain a value for
key
return
null
| |
sourceFailed(source)
| Mark the image URL specified in
source
as failed. Returns
undefined
| |
hasSourceFailedBefore(source)
| Returns
true
if the
source
has been tagged as failed using
sourceFailed(source)
, otherwise
false
. |

Reducing bundle size

Webpack 4

When using webpack 4 you can rely on tree shaking to drop unused sources when creating your Avatar component like the example below.

import { createAvatarComponent, TwitterSource } from 'react-avatar';

const Avatar = createAvatarComponent({ sources: [ TwitterSource ] });

Exported sources: - GravatarSource - FacebookSource - GithubSource - SkypeSource - ValueSource - SrcSource - IconSource - VKontakteSource - InstagramSource - TwitterSource - GoogleSource - RedirectSource

Without Webpack >= 4

If you are using a version of webpack that does not support tree shaking or are using a different bundler you'll need to import only those files you need.

ES6 modules

import createAvatarComponent from 'react-avatar/es/avatar';
import TwitterSource from 'react-avatar/es/sources/Twitter';

const Avatar = createAvatarComponent({ sources: [ TwitterSource ] });

Transpiled ES5 javascript / commonjs

const createAvatarComponent = require('react-avatar/lib/avatar').default;
const TwitterSource = require('react-avatar/lib/sources/Twitter').default;

const Avatar = createAvatarComponent({ sources: [ TwitterSource ] });

Products using React Avatar

Contributing

  1. Fork it!
  2. Create your feature branch:
    git checkout -b my-new-feature
  3. Commit your changes:
    git commit -m 'Add some feature'
  4. Push to the branch:
    git push origin my-new-feature
  5. Submit a pull request :D

History

For detailed changelog, check Releases.

Maintainers

License

MIT License

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.