smart-avatar

Render avatars with dynamic, defined fallback

Table of Contents

• Live Demo
• Usage
  • Basic Example
  • Detailed Example
• Guide to Settings
  • Priority Setting
  • General Settings
  • Gravatar Settings
  • User-defined Source
  • Smart Resource Settings
  • "unstyled" Flag
  • "setDefaults" Flag
• Available Icon Options
  • SmartAvatar Icons
  • Gravatar-hosted Icons
• 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:

import smartAvatar from 'smart-avatar'
const targetElement = document.querySelector('.topbar-user');

smartAvatar(targetElement, {
  "email": "[email protected]",
  "initials": "JG",
  "src": "./user-imgs/jared.jpg",
  "icon": "identicon"
  "round": true,
  "size": 48,
  "color": "#00AE55",
  "textColor": "#FFF",
  "cssClass": "we-user",
});

ES Module:

<script type="module">
  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'),
    });
  }
</script>

Detailed Example

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": "[email protected]",              // 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 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:

<div style="
    align-items: center;
    display: flex;
    font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Oxygen-Sans, Ubuntu, Cantarell, "Helvetica Neue",
        sans-serif;
">
    <span style="
        display: flex;
    ">
        ${content}
    </span>
</div>

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

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)

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