avatar-initials
v6.0.0
Published
JavaScript library for showing Gravatars or generating user avatars from initials.
Downloads
6,584
Maintainers
Readme
Avatar
Avatar is a JavaScript library & React component for showing Gravatars or generating user avatars.
Examples
There are several examples on the website.
import Avatar from 'avatar-initials';
// or
const Avatar = require('avatar-initials');
// Add an avatar to an <img>
const avatar = Avatar.from(document.getElementById('avatar'), {
'useGravatar': false,
'initials': 'MC',
});
// If you just want the URL / string:
const github_avatar_url = Avatar.githubAvatar({
id: '12345'
});
const gravatar_url_from_email = Avatar.gravatarUrl({
email: '[email protected]'
});
const gravatar_url_from_hash = Avatar.gravatarUrl({
hash: '12929016fffb0b3af98bc440acf0bfe2'
});
const initial_png = Avatar.initialAvatar({
initials: 'MC',
initial_fg: '#888888',
initial_bg: '#f4f6f7',
initial_size: 0, // Defaults to height / 2
initial_weight: 100,
initial_font_family: "'Lato', 'Lato-Regular', 'Helvetica Neue'",
});
This example will render an avatar with my initials "MC" as the image.
A simple React example:
import { AvatarComponent } from 'avatar-initials';
export default function Example() {
// ...
return (
<div className={`w-full flex self-center items-center justify-between relative ${classes}`}>
<button type="button" onClick={() => setShowMenu(true)} title="Open Menu">
<AvatarComponent
classes="rounded-full"
useGravatar={false}
size={44}
primarySource={currentUser.Avatar}
color="#000000"
background="#f1f1f1"
fontSize={16}
fontWeight={400}
offsetY={24}
initials={`${currentUser.FirstName[0]}${currentUser.LastName[0]}`}
/>
</button>
</div>
);
}
Options
Avatar is highly customizable and most options are self explanatory:
{
primarySource: '', // A source image to be used by default before attempting any other sources.
fallbackImage: '', // URL or Data URI used when no initials are provided and not using Gravatars.
size: 80, // Size in pixels, fallback for hidden images and Gravatar
setSourceCallback: () => {}, // Callback called when image source is set (useful to cache avatar sources provided by third parties such as Gravatar)
// Initial Avatars Specific
initials: '', // Initials to be used
color: '#888888', // Text Color
background: '#f4f6f7', // Background Color
fontSize: 0, // Text Size in pixels
fontWeight: 100, // Font weight (numeric value for light, bold, etc.)
fontFamily: "'Lato', 'Lato-Regular', 'Helvetica Neue'",
offsetX: undefined, // Text X position in pixels, defaults to: width / 2
offsetY: undefined, // Text Y position in pixels, defaults to: height / 2
width: undefined, // The width of the output image, size is used it not provided
height: undefined, // The height of the output image, size is used if not provided
// Gravatar Specific
useGravatar: true, // Allow Gravatars as source
useGravatarFallback: false, // Use Gravatars fallback, not fallbackImage
hash: '', // Precalculated MD5 string of an email address
email: '', // Email used for the Gravatar
fallback: 'mm', // Fallback Type
rating: 'x', // Gravatar Rating
forcedefault: false, // Force Gravatar Defaults
// GitHub Specific
githubId: null, // GitHub User ID.
}
Installation
npm install --save avatar-initials
or copy the minified build from browser/
<script src="browser/avatar.js"></script>
The browser build is built with the following @babel/preset-env
targets:
{
"android": "109",
"chrome": "109",
"edge": "109",
"firefox": "109",
"ios": "16.2",
"opera": "92",
"safari": "16.2",
"samsung": "19"
}
jQuery Wrapper for Avatar
if (typeof jQuery !== 'undefined') {
jQuery.fn.avatar = function avatar(options) {
return this.each(() => {
if (!jQuery.data(this, 'plugin_avatar')) {
jQuery.data(this, 'plugin_avatar', new Avatar(this, options));
}
});
};
}
Migrating to v6
The settings have changed keys and some new logic was introduced, the logic should not interefere but the keys will need to be updated:
initial_fg => color
initial_bg => background
initial_size => fontSize
initial_weight => fontWeight
initial_font_family => fontFamily
allowGravatarFallback => useGravatarFallback
github_id => github_id
Thanks
Pretty styles and design support kindly provided by Andrew Crocker.
Sun Knudsen for providing a PR with setSourceCallback
.
License
Avatar is MIT licensed.