https://github.com/jaredgorski/smart-avatar
Render avatars with dynamic, defined fallback
https://github.com/jaredgorski/smart-avatar
avatar avatar-api avatar-component avatar-generator custom gravatar gravatar-api initials initials-avatar placeholder profile profile-picture user-interface
Last synced: 10 months ago
JSON representation
Render avatars with dynamic, defined fallback
- Host: GitHub
- URL: https://github.com/jaredgorski/smart-avatar
- Owner: jaredgorski
- License: gpl-3.0
- Created: 2019-01-19T17:05:17.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2023-03-04T14:52:41.000Z (about 3 years ago)
- Last Synced: 2024-12-02T11:59:14.786Z (over 1 year ago)
- Topics: avatar, avatar-api, avatar-component, avatar-generator, custom, gravatar, gravatar-api, initials, initials-avatar, placeholder, profile, profile-picture, user-interface
- Language: JavaScript
- Homepage: https://www.npmjs.com/package/smart-avatar
- Size: 23.8 MB
- Stars: 66
- Watchers: 3
- Forks: 1
- Open Issues: 14
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# smart-avatar [](https://travis-ci.com/jaredgorski/smart-avatar)  
Render avatars with dynamic, defined fallback
---
# Table of Contents
* [Live Demo](#live-demo)
* [Usage](#usage)
* [Basic Example](#basic-example)
* [Detailed Example](#detailed-example)
* [Guide to Settings](#guide-to-settings)
* [Priority Setting](#priority-setting)
* [General Settings](#general-settings)
* [Gravatar Settings](#gravatar-settings)
* [User-defined Source](#user-defined-source)
* [Smart Resource Settings](#smart-resource-settings)
* ["unstyled" Flag](#unstyled-flag)
* ["setDefaults" Flag](#setdefaults-flag)
* [Available Icon Options](#available-icon-options)
* [SmartAvatar Icons](#smartavatar-icons)
* [Gravatar-hosted Icons](#gravatar-hosted-icons)
* [Develop and Test](#develop-and-test)
---
# Live Demo
A live demo is hosted at the following link. This demo allows for experimentation with all of the configuration settings smart-avatar provides. This demo may help you to determine whether this package is right for your needs. Demo will be updated with major changes to functionality.
### https://smart-avatar-demo.jaredgorski6.now.sh/
---
# Usage
## Basic Example
#### JS:
```javascript
import smartAvatar from 'smart-avatar'
const targetElement = document.querySelector('.topbar-user');
smartAvatar(targetElement, {
"email": "jared.gorski@liferay.com",
"initials": "JG",
"src": "./user-imgs/jared.jpg",
"icon": "identicon"
"round": true,
"size": 48,
"color": "#00AE55",
"textColor": "#FFF",
"cssClass": "we-user",
});
```
#### ES Module:
```html
import smartAvatar from 'path-to-module/dist/index.browser.js';
const targetElements = document.querySelectorAll('.avatar');
targetElements.forEach(element => {
smartAvatar(element, {
"email": element.getAttribute('email'),
"initials": element.getAttribute('initials'),
"src": `./user-imgs/${element.getAttribute('name')}.jpg`,
"icon": "retro"
"round": true,
"size": element.getAttribute('size'),
});
}
```
## Detailed Example
```javascript
import smartAvatar from 'smart-avatar';
// define target element to append with smart-avatar
const targetElement = document.querySelector(.topbar-user);
// run smartAvatar function, passing target element and desired configuration
smartAvatar(targetElement, {
// fallback priority definition
"priority": [
"gravatar",
"src",
"smart"
],
// general settings
"cssClass": "site-avatar", // user-defined CSS classes
"round": true, // shape of asset (square if false)
"size": 80, // size of asset (width in px)
"timestamp": true // adds timestamp attribute (for unique id)
"alt": "User jaredgorski profile image" // adds alt attribute for accessibility (if not initials or smartfox)
// gravatar settings
"email": "jared.gorski@liferay.com", // gravatar email address
"format": "png", // gravatar image format (jpg, png, or tiff)
"hash": "93a5c828f0da09f0af10d2ac238724b5", // md5 hash of gravatar email address
"protocol": "secure", // protocol of gravatar request (secure, unsecure, or agnostic)
"resolution": 120, // resolution of gravatar (width in px)
// user-defined src
"src": "./img/src.jpg", // path to custom fallback asset, relative or absolute
// initials settings
"initials": "J", // 1 or 2 letters
"color": "#AAAAAA", // color of background (affects both initials and built-in icon)
"textColor": "#FFFFFF", // color of initials font
// built-in icon
"icon": "smartfox", // see below for available icon styles
// customization and defaults
"unstyled": false, // renders smart-avatar with no inline styles (for stylesheets)
"setDefaults": true, // sets styled defaults for size, color, and textColor
});
```
# Guide to Settings
## Priority Setting
Key | Definition | Default
--- | --- | ---
`priority` | **Array** - Defines fallback order. | `['gravatar', 'src', 'smart']`
The priority setting consists of up to 3 items:
- **gravatar**: Attempts to render a gravatar asset if `email` address and/or `hash` is provided.
- **src**: Attempts to render a user-defined asset.
- **smart**: Attempts to render an initials avatar if `initials` is provided, or an icon if not. If no [valid icon option](#available-icon-options) is provided, the `smartfox` icon will be rendered.
In the case of **gravatar** and **src**, these options will fall back to the next option in the priority array. So, **gravatar** will fall back to **src** (and vice-versa) and/or will finally fall back to **smart** of no valid data was provided to render a **gravatar** or **src** asset.
Once **smart** is reached, the smart-avatar will look for `initials`. If none are provided, it will fall back to any defined `icon`, and finally to the `smartfox`. This means that, if **smart** is included *before* **gravatar** or **src**, any data for the latter option will not be reached in the priority queue and will therefore not be rendered. Also, even if **smart** is not included in the array, the `smartfox` icon will serve as a final fallback.
## General Settings
Key | Definition | Default
--- | --- | ---
`alt` | **String** - Adds `alt` attribute to img element output. | N/A
`cssClass` | **String** - Adds custom CSS classes. | N/A
`round` | **Boolean** - Generates output with border-radius of 50%. | `false`
`size` | **Number or String** - Defines output element width in `px`. | N/A
`timestamp` | **Boolean** - Adds `sa_timestamp` attribute with milliseconds elapsed since the UNIX epoch. | `false`
These settings apply to the rendered element in general. One can add CSS classes for use by custom stylesheets, define the size and shape of the rendered element, add a timestamp for debugging or use as a unique id (obviously this value is not permanent), and add an `alt` attribute for accessibility purposes.
## Gravatar Settings
Key | Definition | Default
--- | --- | ---
`email` | **String** - Relative or absolute path to desired asset. | N/A
`format` | **String** - Image format to request from Gravatar: *jpg, png, or tiff.* | `jpg`
`hash` | **String** - md5 hash of Gravatar email address. | N/A
`protocol` | **String** - Protocol to use for Gravatar request: *secure (https), unsecure (http), or agnostic (//).* | `secure`
`resolution` | **Number or String** - Defines gravatar resolution (width) in `px`. Does not affect size. Best at 150% of size. | `80`
Defining these settings enables rendering a Gravatar user image by requesting a resource from Gravatar for a given user's email address. Many aspects of this request and output can be customized, including the request protocol, resource format, and image resolution. Keep in mind that higher resolutions result in more data transfer, meaning larger requests.
## User-defined Source
Key | Definition | Default
--- | --- | ---
`src` | **String** - Relative or absolute path to desired asset. | N/A
Providing a path to a custom resource allows for proprietary icons and user images to be used as primary avatars or fallback resources.
## Smart Resource Settings
Key | Definition | Default
--- | --- | ---
`color` | **String** - Background color of smart icon as Hex, RGB, or RGBA value. | N/A
`icon` | **String** - Defines smart icon style. | `smartfox`
`initials` | **String** - 1 or 2 letters to use as initials. | N/A
`textColor` | **String** - Font color of initials icon as Hex, RGB, or RGBA value. | N/A
The "smart" resource is so-called because it provides an easy API for quality fallback in the worst-case scenario. If the given **gravatar** data doesn't return a valid image and the **src** path is broken, an asset with a given user's initials or a general, non-specific icon makes for a great avatar. If an icon is preferred, there are plenty of options to choose from, with more to come. See the list of available icons below.
_Note: `color` and `textColor` only matter in the case of a non-Gravatar icon or an initials avatar._
_Also note: in the future, the initials avatar will be made more available, rather than simply being a fallback option._
## "unstyled" Flag
Even with no settings defined, a non-Image smart-avatar will _still_ have the following inline styles:
```html
${content}
```
This means that, if you wish to customize the font of your initials avatar or change the layout styles for some reason, simply leaving all of the settings undefined will still get in the way of stylesheet customizations for the properties defined inline above (unless you use `!important`, but that defies best-practices).
This is where the `unstyled` flag comes in handy. If you want your smart-avatar asset to be completely raw and unstyled to make room for your stylesheets, you should pass `unstyled: true`. This will override any settings for that smart-avatar asset, always returning pure HTML. This means that images will render at their natural sizes, there will be no layout structure, and background colors, text colors, and font styles will all default to User-Agent unless styled otherwise. This makes smart-avatar a flexible solution for nearly any application.
## "setDefaults" Flag
If you're looking for quick and dirty results, passing `setDefaults: true` in your configuration will change the default behavior of `color`, `size`, and `textColor` to the following:
Key | Definition | Default
--- | --- | ---
`color` | **String** - Background color of smart icon as Hex, RGB, or RGBA value. | `#AAAAAA`
`size` | **Number or String** - Defines output element width in `px`. | `48`
`textColor` | **String** - Font color of initials icon as Hex, RGB, or RGBA value. | `#FFFFFF`
Since the `setDefaults` flag _only changes the default behavior_ of these settings, that means that defining these settings yourself will still override these defaults. For example, a smart-avatar asset with `setDefaults: true` and `size: 120` will render with a size of 120px, a background color of `#AAA`, and a font color of `#FFF`.
_Note: `color` and `textColor` only matter in the case of a non-Gravatar icon or an initials avatar._
## Disposal
```javascript
import smartAvatar from 'smart-avatar';
const targetElement = document.querySelector(.topbar-user);
// ... code ...
smartAvatar(targetEl, 'dispose');
```
There may come a time where you want to dispose of all smart-avatar assets that are child-nodes of a given element. By passing a parent element alongside the string `dispose` in place of the configuration object, you can remove all smart-avatar nodes from the given parent element.
# Available Icon Options
## SmartAvatar Icons
**smartfox** - the best default fox ever (uses `color` as background)
## Gravatar-hosted Icons
_([from their website](https://en.gravatar.com/site/implement/images/))_
**mp** - (mystery-person) a simple, cartoon-style silhouetted outline of a person (does not vary by email hash)
**identicon** - a geometric pattern based on an email hash
**monsterid** - a generated 'monster' with different colors, faces, etc
**wavatar** - generated faces with differing features and backgrounds
**retro** - awesome generated, 8-bit arcade-style pixelated faces
**robohash** - a generated robot with different colors, faces, etc
---
# Develop and Test:
`npm i`
*(write code)*
`npm run test`