Say Hello to Avataaars.js: Lightweight, Dependency-Free Avatars for the Modern Web 🚀

Are you tired of importing heavy React libraries, pulling in massive node modules, or hitting API rate limits just to render a simple, beautiful user avatar?

Meet Avataaars.js! A lightweight, zero-dependency, and fully customizable avatar generator implemented entirely as native HTML Custom Elements (Web Components).

Designed using modern, vanilla JavaScript and ES modules, Avataaars.js runs natively in the browser. It gives you rich customization, smooth built-in animations, serialization, and dynamic chunk loading out of the box—with a minified entry point of only ~31 KB!

Avataaars.js is built using the wonderful Avataaars sketch library by Pablo Stanley.

Let’s take a look at what makes it so special.

🎨 The Interactive Customizer

Creating your ideal avatar is as simple as tweaking a few drop-downs. The library comes with a sleek, premium interactive dashboard that lets you design, randomize, and serialize your custom avatar in real-time.

Avataaars.js Customizer Dashboard

🚀 Key Features

1. Declaring Avatars Natively in HTML

Say goodbye to complex React JSX structures. Simply load the module and declare <avataaars-avatar> directly in your HTML document.

<!-- Load the Custom Element -->
<script type="module"src="./dist/avataaars.min.js"></script>

<!-- Build your custom look with simple attributes -->
<avataaars-avatar
  backdrop-type="Circle"
  backdrop-color="PastelBlue"
  skin-color="Pale"
  top-type="ShortHairShaggy"
  hair-color="Black"
  clothe-type="Hoodie"
  clothe-color="Red"
/>

Under the hood, Avataaars.js handles rendering using the browser-native Shadow DOM, which keeps the SVG styles and dynamic mask IDs fully encapsulated. This guarantees that your avatar’s styles will never leak out or conflict with the styles on your main website.

2. Save, Share, and Load via Compact 15-Character Hashes

Want to save a user’s avatar configuration to a database or share it via a URL? Instead of saving a giant JSON object, Avataaars.js serializes any configuration into a ultra-compact 15-character Base-62 hash.

<!-- Instantly instantiate the exact same custom avatar from a hash -->
<avataaars-avatar hash="18K2934D2165037" animated />

You can seamlessly extract the hash or load configurations programmatically:

import { getAvatarHash, getAvatarConfigFromHash } from './src/avataaars.js';

// Retrieve the base62 representation
const hash = getAvatarHash(interactiveAvatar.getOptions()); // e.g. "18K2934D2165037"

import { getAvatarHash, getAvatarConfigFromHash } from'./src/avataaars.js';


// Retrieve the config object
const config = getAvatarConfigFromHash("18K2934D2165037")
interactiveAvatar.setOptions(config));

3. Dynamic Randomization

Want to generate unique avatars for new users? Avataaars.js makes randomization effortless. Simply add the randomize attribute to the element, or drop in a nested <avataaars-randomize> element.

<!-- Explicitly set clothing, but randomize everything else! -->
<avataaars-avatar clothe-type="Hoodie" clothe-color="Red" randomize />

<!-- Or randomize dynamically using the sub-component -->
<avataaars-avatar>
  <avataaars-randomize />
</avataaars-avatar>

The built-in coordinate system is smart enough to prevent color clashes, so you’ll always get a gorgeous, cohesive looking character. Here is an example generated by hitting the randomizer:

Random Avatar Generator

4. Smooth Micro-Animations

Avatars don’t have to be static. Adding the animated attribute activates subtle CSS keyframe animations for natural blinking, nose twitches, and mouth movements.

<avataaars-avatar hash="18K2934D2165037" animated />

To keep your UI looking natural when multiple avatars are displayed together, the library automatically assigns a randomized animation-delay (from 0s to 5s) to each element, ensuring they don’t blink in creepy, synchronized unison!

5. Custom Color Palettes at Runtime

Need custom gradients, brand colors, or seasonal themes? The JavaScript API allows you to inject brand new colors dynamically:

import { addPaletteColor } from './src/avataaars.js';

// Register a transparent backdrop color
addPaletteColor('BACKDROP', 'Transparent', 'rgba(0,0,0,0)')

// Register a new 'SunsetGlow' linear gradient for the backdrop
addPaletteColor('BACKDROP', 'SunsetGlow', {
  type:'linear',
  attrs:
    { 
      x1: '0%',
      y1: '0%'
      x2: '100%',
      y2:'100%'
    },
  stops: [
    { offset: '0%', color: '#ff7e5f' },
    { offset: '100%', color: '#feb47b' }
  ]
});

🛠️ Built for Speed and Performance

Even though Avataaars offers thousands of visual combinations (hair styles, facial expressions, apparel, and accessories), it won’t impact your page-load speed.

Thanks to ESM Code-Splitting and a custom build pipeline:

1. The main entry point (avataaars.min.js) loads instantly.
2. SVG elements, accessory coordinates, and hair graphics are split into separate chunk files.
3. Chunks (like eyes-*.js, top-*.js) are loaded on-demand and lazily only when that specific asset is requested.

This keeps initial page load extremely fast, keeping search engines happy and Core Web Vitals clean!

⚡ Get Started Today!

Avataaars.js is open-source and released under the MIT License.

• GitHub Repository: github.com/gschoppe/avataaars.js
• Live Demo: gschoppe.github.io/avataaars.js

Give your web apps a fresh, dynamic look with native web component avatars today!