<Avatar> 
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.
For the moment we support following types:
- GitHub
- Twitter (using Avatar Redirect)
- Instagram (using Avatar Redirect)
- Vkontakte (using Avatar Redirect)
- Skype
- Gravatar
- Custom image
- Name initials
The fallbacks are in the same order as the list above were Facebook has the highest priority.
Demo
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 --saveOr download as ZIP.
Usage
-
Import Custom Element:
import Avatar from 'react-avatar';
-
Start using it!
<Avatar name="Foo Bar" />
Some examples:
<Avatar googleId="118096717852922241760" size="100" round={true} /> <Avatar facebookId="100008343750912" size="150" /> <Avatar githubHandle="sitebase" size={150} round="20px" /> <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 | ||
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 |
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'; <ConfigProvider colors={['red', 'green', 'blue']}> <YourApp> ... <Avatar name="Wim Mostmans" /> ... </YourApp> </ConfigProvider> 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 <ConfigProvider cache={cache}> <YourApp> ... <Avatar name="Wim Mostmans" /> ... </YourApp> </ConfigProvider> // For specific instances <Avatar name="Wim Mostmans" cache={cache} /> 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:
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
libandesfolders.$ 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. |
Products using React Avatar
Contributing
- Fork it!
- Create your feature branch:
git checkout -b my-new-feature - Commit your changes:
git commit -m 'Add some feature' - Push to the branch:
git push origin my-new-feature - Submit a pull request :D
History
For detailed changelog, check Releases.
Maintainers
- @Sitebase (Creator)
- @JorgenEvens
