Add gender switch to avataaars

[smeijer]

Would be nice to have a gender (male|female) option for the avataaars. I tried to fake it by setting the hair length. But then I get "females" with mustaches.

I know, nothing wrong with that... But also not suited for all my users.

[FlorianKoerner]

I had once decided against such an option. Because as you have already mentioned: What is female and what is male?

However, you can define the options so that either a very female or a very male character comes out. The configurator on avatars.dicebear.com might also help.

For example, there is also an option on how likely it is that the character has a mustache.

Examples:

Female: https://avatars.dicebear.com/v2/avataaars/example.svg?options[top][]=longHair&options[top][]=hat&options[topChance]=100&options[accessoriesChance]=40&options[facialHairChance]=0

Male: https://avatars.dicebear.com/v2/avataaars/example.svg?options[mode]=exclude&options[top][]=longHair&options[topChance]=80&options[hatColor][]=pastel&options[hatColor][]=pink&options[hatColor][]=red&options[hairColor][]=red&options[hairColor][]=pastel&options[accessoriesChance]=10&options[facialHairChance]=80&options[facialHairColor][]=red&options[facialHairColor][]=pastel&options[clothesColor][]=red&options[clothesColor][]=pink&options[eyes][]=hearts

[smeijer]

fair enough.

[AmineAssali]

Hello @FlorianKoerner i remember that i have tested the http request you have posted about a year ago and it worked, but now it doesn't work, do you have any idea why ??

Thanks in advance.

[FlorianKoerner]

@AmineAssali you are right. The following links should work.

Long Hair & without facialHair
https://api.dicebear.com/5.x/avataaars/svg?facialHairProbability=0&top=bigHair,bob,bun,curly,curvy,dreads,frida,fro,hijab,longButNotTooLong,miaWallace,shaggy,shaggyMullet,shavedSides,straightAndStrand,straight01,straight02&seed=YOUR_SEED_HERE

Short Hair
https://api.dicebear.com/5.x/avataaars/svg?top=dreads01,dreads02,eyepatch,frizzle,shortCurly,shortFlat,shortRound,shortWaved,sides,theCaesar,theCaesarAndSidePart,turban&seed=YOUR_SEED_HERE

[bitcloudTheFirst]

This is definitely a bug. Having avatars that don't generate reliable genders makes a great system useless.

[FlorianKoerner]

We see it differently. This is working as intended, not a bug.

DiceBear generates a varied avatar from each seed by design. It has no built-in notion of gender that could be generated "reliably," so there is no defect to fix here.

Reliable gender output was never a goal, because there is no universal set of features that reads as male or female across cultures and people. If you do need avatars to lean a certain way, that is exactly what the options are for. They also apply to seed-based generation, so you can constrain what a seed is allowed to produce and still get a deterministic result. There is a short guide here: https://www.dicebear.com/guides/how-do-i-set-a-gender/

[EvanCarroll]

I had once decided against such an option. Because as you have already mentioned: What is female and what is male?

Even if you wanted to avoid a binary based on gender, the right solution is to put it (or more specifically femininity and masculinity) on a spectrum. Not to force those who want a masculine/male avatar into opting for mustaches. As if to say, a man that doesn't have a mustache can't be male because the API doesn't allow for this.

I think it's GREAT that the project supports hijabs and turbans. But, for everyone including Muslims and Sikhs it would have to be downright awkward to join a service powered by dicebear, and find yourself as a person that identifies as a male with an avatar adorned with hijab, or a female with an avatar adorned with a turban. And the alternative is what? To ask your users what their religion is, and what their gender is and to manually map in the turban and hijab? That's a lot of work that would forever limit the ability to support multiple graphic sets.

It's like there are two conflicting use cases.

• Make your own avatar entirely from scratch.
• Generate an avatar from a seed (like an email address) and a baseline of information, perhaps age and gender. Like a more relatable identicon.

[FlorianKoerner]

These are fair points, and the two use cases you describe are a useful way to frame this.

For the seed-based case, the options are not only for hand-building a single avatar. They also define the pool and the probabilities that a seed draws from. So you can constrain what a seed is allowed to produce (for example, set facialHairProbability, or remove tops like a hijab or turban from the pool) and the result stays deterministic per seed. That covers the mismatch you describe without having to hand-map each user.

What DiceBear does not do is map an abstract attribute like "gender" or "religion" onto features, and that is the part we deliberately leave to you. There is no universal mapping from such an attribute to a set of features, so wherever that mapping lives, someone has to make culturally specific choices. We would rather that decision sit with you, who knows your audience, than be built into the library for everyone.

A femininity and masculinity spectrum runs into the same thing underneath. A slider still needs DiceBear to decide which features move along the axis and in which direction, which is exactly the culturally loaded mapping we are trying to avoid. It would move the problem behind a control rather than remove it.

You are right that building your own attribute-to-option mapping is extra work, and that it is style specific because each style has different components. The options.json endpoint and the OptionsDescriptor class let you read a style's available options at runtime, which makes that mapping easier to build and keep working across styles.

[FlorianKoerner]

There is no dedicated gender option in DiceBear, and this is on purpose. You can still get the avatars you have in mind by setting the options yourself.

Every style exposes its features as individual options, so you can choose the hair, facial hair, clothing, and so on that fit the look you want. The same options apply to seed-based generation: they define the pool a seed draws from, so you can narrow that pool (for example, remove facial hair or restrict the hair to certain styles) and still get a deterministic avatar per seed. There is a short guide that walks through this: https://www.dicebear.com/guides/how-do-i-set-a-gender/

We deliberately do not ship a built-in "male" or "female" default. What reads as masculine or feminine is not universal. It varies between cultures and between people. Any default we picked would build one interpretation into the library and apply it to everyone, which would not fit every project or audience. We would rather give you the controls and let you define it for your own context.

If your goal is to avoid features that tend to read as gendered, several styles also have a *-neutral variant (for example avataaars-neutral, adventurer-neutral, and lorelei-neutral). These drop things like hair and accessories that often carry those signals. That said, they are not truly neutral either. A rendered face still has a skin tone and features that can read as a particular ethnicity, so no style is free of signals. "Neutral" here means reduced, not absent.

[EvanCarroll]

Would you bless a fork of this project that addressed this need? Or would you interpret it as hostile?

It's not my goal to create drama or beef, but I have a different direction that I need. I love what you've done, and I would suggest this for any character creation screen or the like. But it's brutal to integrate this for my workflow. And I'm not going to get any use for my own product without an improvement here which seems like it's not desired even if built.

I have a need and it's in philosophical opposition to this project.

---

But as a side note, I wish we lived in a post-gender society. But I wasn't cultured that way, and I'm going to lose demonstrably 95% of my audience without some cultural awareness here.

[FlorianKoerner]

Forking is fine. DiceBear Core is MIT licensed, so you can copy it, change it, and ship it without my blessing, and I would not read that as hostile. No drama on my end.

But I would rather find something that works for both of us, because I think most of what you need is close to the surface already.

Here is what works today. You define, for your own audience, which options read as masculine or feminine and hand DiceBear those pools as a preset. The seed still drives the result, so you keep the deterministic identicon behavior:

DiceBear 10.x

import { Style, Avatar } from '@dicebear/core';
import definition from '@dicebear/styles/avataaars.json' with { type: 'json' };

// You decide what masculine and feminine mean for your users.
// DiceBear only draws from the pools you give it.
const presets = {
  masculine: {
    topVariant: ['shortFlat', 'shortRound', 'shortCurly', 'shortWaved', 'theCaesar', 'sides'],
    facialHairProbability: 50,
  },
  feminine: {
    topVariant: ['longButNotTooLong', 'bob', 'curvy', 'straight01', 'straight02', 'bigHair'],
    facialHairProbability: 0,
  },
}

const svg = (seed, gender) =>
  new Avatar(style, { seed, ...presets[gender] }).toString()

svg('alex@example.com', 'masculine')
svg('robin@example.com', 'feminine')

DiceBear 9.x

import { createAvatar } from '@dicebear/core'
import { avataaars } from '@dicebear/collection'

// You decide what masculine and feminine mean for your users.
// DiceBear only draws from the pools you give it.
const presets = {
  masculine: {
    top: ['shortFlat', 'shortRound', 'shortCurly', 'shortWaved', 'theCaesar', 'sides'],
    facialHairProbability: 50,
  },
  feminine: {
    top: ['longButNotTooLong', 'bob', 'curvy', 'straight01', 'straight02', 'bigHair'],
    facialHairProbability: 0,
  },
}

const svg = (seed, gender) =>
  createAvatar(avataaars, { seed, ...presets[gender] }).toString()

svg('alex@example.com', 'masculine')
svg('robin@example.com', 'feminine')

Same seed, same avatar, every time. The seed only draws from the pool you allowed.

Now the honest part, because I think this is what you were really pointing at. This preset is tied to specific variant names, and it covers one style. If you offer several styles, you write one preset per style. And when a style gains new variants in a later version, your allowlist can quietly fall behind. That maintenance is real, and "just use OptionsDescriptor" does not make it disappear. OptionsDescriptor tells you which options exist. It does not tell you that shortFlat is short hair and bob is long hair. Right now that knowledge lives in your head.

So here is the direction I would actually consider, and where I want your take. What if every variant carried descriptive tags in the style data itself. Not "masculine" or "feminine", but objective descriptors you can read straight off the asset: hair length (long, short, none), facial hair (present, absent), headwear type (casual, religious, cold-weather). You would then filter by tag instead of by hard-coded names:

// sketch, not a real API yet
tags: ['hair:short', '!earrings'],
facialHairProbability: 50,

Two things fall out of that. New variants get tagged by whoever adds them, so your filter keeps working across versions without you touching it. And the cultural call stays with you. DiceBear says "this is short hair", you decide that short hair is part of what masculine means for your audience. That split is the part I care about. I will not bake "masculine" into the library, because that mapping is not universal. Describing the raw features so you do not have to reverse-engineer them per style is something I am glad to do.

The open question is the rest of the components, and I would value your input here. Hair length, facial hair, and headwear tag cleanly, because there is an objective axis, and those are exactly the parts behind your hijab-on-a-man example. A religious-headwear tag alone would let you drop that case entirely. Eyes, nose, and mouth do not have an obvious axis, and I would not force tags onto them just to look complete. So the vocabulary would cover the high-signal parts and stop where it stops being objective.

If that sounds useful, I would rather build it in the open with you than have you carry a fork for something we can solve in the data. Which descriptors would actually unblock your workflow, and across which styles?

[FlorianKoerner]

Here's the plan I worked out for this today.

Quick recap of the part that already works, because I want to make sure it's clear: with the per-component options from my earlier comment (topVariant, facialHairProbability, and so on) you can already narrow which variants the PRNG picks from, and it stays deterministic per seed. That's not a workaround. The same approach already works for plenty of projects running DiceBear in production.

That's the extra work you flagged, though: it goes by variant name, so the mapping is manual and you redo it per style.

That's what I'm adding a tags option for. Variants can carry plain descriptors like hairLength:short or headwear:hat, and you filter on those instead of names:

// planned DiceBear 10 syntax, not shipping yet
createAvatar(avataaars, {
  seed: 'alex@example.com',
  tags: ['hairLength:short', '!headwear:religious'],
})

You're matching descriptors, not names, so one config works across styles. Throw the same tags at avataaars, lorelei, adventurer, and each one lands on variants that fit your own idea of masculine or feminine, without reading every style's variant list.

And if the tags we ship don't cover what you want, fork a style and add your own, gender:male / gender:female included if that's what fits your product. Styles are just JSON data, so that fork is editing a JSON file, not maintaining a code fork. Tag the variants once and your tags config picks them up.

Fair warning: it's mid-implementation, no shipped code yet. So the tags snippet is the planned DiceBear 10 syntax, not something you can run today. The options approach already works.

[EvanCarroll]

Really busy now, just fyi. Give me 48 hours to read and respond. I'll do it the second I get a chance though.

[FlorianKoerner]

First draft #536