/react-avatar

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

Primary LanguageJavaScriptMIT LicenseMIT

<Avatar>Build Status

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:

  • Facebook
  • Google
  • Twitter
  • Vkontakte
  • Skype
  • Gravatar
  • Custom image
  • Name initials

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 react-addons-shallow-compare and prop-types
# as peer dependencies, make sure to install the correct version
# for your version of react
$ npm install react-addons-shallow-compare@^0.14 --save
# OR
$ npm install react-addons-shallow-compare@^15 --save

Or download as ZIP.

Usage

  1. Import Custom Element:

    import Avatar from 'react-avatar';

  2. Start using it!

    <Avatar name="Foo Bar" />

Some examples:

<Avatar googleId="118096717852922241760" size="100" round={true} />
<Avatar facebookId="100008343750912" size="150" />
<Avatar vkontakteId="1" size="150" />
<Avatar skypeId="sitebase" size="200" />
<Avatar twitterHandle="sitebase" size="40" />
<Avatar name="Wim Mostmans" size="150" />
<Avatar name="Wim Mostmans" size="150" textSizeRatio="1.75" />
<Avatar value="86%" size="40" />
<Avatar size="100" facebook-id="invalidfacebookusername" src="http://www.gravatar.com/avatar/a16a38cdfe8b2cbd38e8a56ab93238d3" />
<Avatar name="Wim Mostmans" unstyled="true" />

Manually generating a color:

import Avatar from 'react-avatar';

<Avatar color={Avatar.getRandomColor('sitebase', ['red', 'green', 'blue'])} name="Wim Mostmans" />

Configuring React Avatar globally

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

<ConfigProvider colors={['red', 'green', 'blue']}>
    <YourApp>
        ...
        <Avatar name="Wim Mostmans" />
        ...
    </YourApp>
</ConfigProvider>

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
googleId string
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
value string Show a value as avatar
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)
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

Development

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

  • Install local dependencies:

    $ npm install

  • Auto build new test version when developing that can be run with grunt connect:

    $ npm run dev

  • To test your project, start the development server and open http://localhost:8000/index.html.

    $ python -m SimpleHTTPServer

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.

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