With Avataaars you can create avatar icons by combining clothes, hair, emotions, accessories, and colors.

1.0.2 2020-09-08 08:39 UTC

This package is auto-updated.

Last update: 2021-11-08 11:29:14 UTC


With Avataaars for Craft CMS you can create avatar icons by combining clothes, hair, emotions, accessories, and colors. This plugin is based on the Avataaars set designed by Pablo Stanley and the HTTP API provided by Dicebear.


This plugin requires Craft CMS 3.0.0-beta.23 or later.


To install the plugin, follow these instructions.

  1. Open your terminal and go to your Craft project:

     cd /path/to/project
  2. Then tell Composer to load the plugin:

     composer require remcoov/avataaars
  3. In the Control Panel, go to Settings → Plugins and click the “Install” button for Avataaars.

Using Avataaars

In your twig templates, you can create a lot of different Avataaars by playing with all the available settings. The Avataaar icon used for this Craft CMS plugin, for example, is made with the following settings:

{% set avataaar = craft.avataaars.avataaar({
    seed: 'avataaar',
    radius: 0,
    width: 200,
    height: 200,
    margin: 0,
    background: 'CCCCCC',
    style: 'circle',
    top: 'shortHair',
    hatColor: 'red',
    hairColor: 'black',
    accessories: 'prescription02',
    facialHair: 'majestic',
    facialHairColor: 'black',
    clothes: 'hoodie',
    clothesColor: 'pink',
    eyes: 'happy',
    eyebrow: 'flat',
    mouth: 'smile',
    skin: 'light',
    svg: false
}) %}

<img src="{{ avataaar }}" />

Available settings


The value of seed can be anything you like - but don't use any sensitive or personal data here!


Avatar border radius. Max: 50


Fixed width


Fixed height


Avatar margin in percent. Max: 25


Only hex (3-digit, 6-digit and 8-digit) values are allowed. For example: FF0000


transparent or circle


longHair, shortHair, eyepatch, hat, hijab or turban


black, blue, gray, heather, pastel, pink, red or white


auburn, black, blonde, brown, pastel, platinum, red or gray


kurt, prescription01, prescription02, round, sunglasses or wayfarers


medium, light, majestic, fancy or magnum


auburn, black, blonde, brown, platinum or red


blazer, sweater, shirt, hoodie or overall


black, blue, gray, heather, pastel, pink, red or white


close, cry, default, dizzy, roll, happy, hearts, side, squint, surprised, wink or winkWacky


angry, default, flat, raised, sad, unibrow or up


concerned, default, disbelief, eating, grimace, sad, scream, serious, smile, tongue, twinkle or vomit


tanned, yellow, pale, light, brown, darkBrown or black


When you'd like to output the Avataaar as raw SVG code, you'd want to set this to true. Example:

{% set avataaar = craft.avataaars.avataaar({
    svg: true
}) %}

{{ svg(avataaar) }}

If you would like to add a class to the SVG:

{{ svg(avataaar)|attr({ class: 'avataaar-icon' }) }}

Random Avataaar

You can also output a random Avataaar by simply doing the following:

<img src="{{ craft.avataaars.avataaar }}" />

Form to set Craft CMS user photo

You can render a form on the front-end to let (logged in) users set a rendered Avataaar as their Craft CMS user photo. To do this, add the following code:

{% set user = user ?? currentUser %}
{% if user %}

    <form method="POST" id="userPhoto-form">
        {{ craft.avataaars.userPhotoForm|raw }}
        <input type="hidden" name="width" value="300" />
        <input type="hidden" name="height" value="300" />
        <input type="hidden" name="background" value="" /> <!-- f.e. FF0000 -->
        <input type="hidden" name="margin" value="" /> <!-- max. 25 -->

        {{ csrfInput() }}
        <div class="userPhoto-result">
            <img src='data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8Xw8AAoMBgDTD2qgAAAAASUVORK5CYII=' id="userPhoto-result-img" />

        <input id="userPhoto-submit" type="submit" value="Set user photo" >

{% endif %}

The form has a couple of hidden configurations for you as a developer to set, since these are probably too 'technical' for the user: width, height,background and margin.

When the user sets the profile picture and you want to do something on either success or error, you can use the following Javascript code:

window.addEventListener('userPhotoStatus', function (e) {
}, false);

A note beforehand: remember to set the volume for user photo storage.

Brought to you by remcoov and kevinmu17