# How DiceBear tags variants DiceBear's own styles share one set of tags, so the [`tags`](https://www.dicebear.com/guides/filter-variants-with-tags/) filter behaves the same from one style to the next. Today only one category ships: the `animation` tag of the animated styles. The character categories further down arrive with an upcoming release. DiceBear tags each variant by looking at how it renders, not at its name. Names are not always reliable. A hair variant called `long04` can turn out short once you look at it, so the rendered shape decides the tag. A few principles keep the tags consistent: - Tags only describe. A variant carries the labels that fit what it shows, and never a category outside the set below. - A tag is added only when the trait is clear. An ambiguous or purely decorative variant is left untagged rather than guessed. Where a category has a bare form, as `headwear` does, the bare tag is still set and only the value is left off. - Most variants carry no tag or one tag. A few carry two, such as hair with a visible hat. - Variant tags only add information, they never remove a variant on their own. To leave something out at render time, use the `!` form of the [`tags` option](https://www.dicebear.com/guides/filter-variants-with-tags/). Disallowing lives in the filter, not in the data. The tag grammar is `category` or `category:value`, each segment camelCase and alphanumeric. A variant holds at most 32 tags. ## Animation The `animation` category covers the animation component of animated styles. It is a bare category without values: every animated variant carries the plain `animation` tag, and the static default variant carries no tag, so the animation stays off until you ask for it. - `['animation']` turns the animation on, at a random speed per seed. - `['!animation']` keeps the avatar static. A disallow wins, so it also overrides an `animation` in the same list. The speed steps are variants, not traits, so they carry no value tags. To pin a speed, set the `animationVariant` option (e.g. `animationVariant: 'slow'`), which is more specific than the filter and always wins. ## Planned categories > [!WARNING] Not shipped yet > No DiceBear style carries the categories below, so filtering on them has no > effect for now. The categories below are the standard set for the character styles. We publish the definitions ahead of time so custom styles can reuse them and stay compatible with the filter examples in the docs. ### Mood The `mood` category covers the parts of the face that carry expression: the mouth, eyes, eyebrows, and any combined expression component. It has two values, and a variant gets at most one. - `negative` for a clearly unfriendly or distressed expression: angry, sad, or scared. - `positive` for everything else, including happy, neutral, surprised, playful, and confused faces. Only a clear negative is tagged `negative`. Anything friendly, neutral, or ambiguous is `positive`, so filtering on `mood:positive` always leaves a usable variant and never empties a component. The usual reason to filter mood is to keep avatars friendly, and `mood:positive` does that. Mood is deliberately coarse. A finer list of feelings would not survive filtering, because a specific feeling like "sad" often has no matching variant for every part of a face, so that part would drop out and the avatar would render incomplete. Two values keep every filtered face complete. A part with no expression at all, such as a face mask or a purely graphic shape, is left without a mood. ### Hair length The `hairLength` category covers hair components. It is optional and only set when the length is actually visible. - `bald` for no hair, or hair shaved to the scalp. - `short` for hair above the ears, cropped or buzzed. - `medium` for around ear-to-jaw length. - `long` for hair past the jaw, shoulder length or longer. When the hair is gathered or pinned up so the length cannot be read, such as a bun or a top-knot, the length is left off. A ponytail or pigtails with a visible hanging tail still gets a length. A variant that is really headwear gets a `headwear` tag, and a variant showing both hair and a hat may carry both. The cut and the texture of the hair carry no tags. Whether hair reads as wavy or curly is a judgment call that would come out differently from one style to the next, and the filter is there to steer the look in broad strokes, not to pick a haircut. For a specific hairstyle, set the style's own hair variant option. ### Headwear The `headwear` category covers anything worn on the head. Every such variant carries at least the bare `headwear` tag, so `!headwear` removes all of them. A value comes on top of it when the shape is unmistakable: - `hat` for a crown with a brim all the way around, such as a sun hat or a fedora. - `cap` for a brim at the front only, such as a baseball or a flat cap. - `beanie` for a soft, close-fitting hat without a brim. - `turban` for wrapped cloth that covers the hair and leaves the neck free. - `headscarf` for wrapped cloth that covers the hair together with the neck or the shoulders. - `headband` for a band alone, with the hair still visible. The values name the shape of the garment, not the person wearing it. That is why the two wrapped forms are told apart by the neck, and why the tag says `headscarf` rather than naming a particular garment: the drawing shows cloth, and the same cloth means different things to different people. ### Facial hair The `facialHair` category covers beards, mustaches, and sideburns. Like `animation` it is a bare category without values: a variant showing any facial hair carries the plain `facialHair` tag, and a clean-shaven one carries none. - `['!facialHair']` leaves facial hair out. - `['facialHair']` drops the untagged variants of the components that use the category. Whether such a component is drawn at all is still up to its probability. Where stubble ends and a beard begins is a call that would land differently from one style to the next, and what the filter is good for is saying yes or no to facial hair. For a specific beard, set the style's facial hair variant option. ### Eyewear The `eyewear` category covers glasses. - `glasses` for clear lenses or spectacles. - `sunglasses` for filled or dark lenses. ### Accessory The `accessory` category covers worn extras. - `earrings` for ear jewelry. - `mask` for a face covering worn over the mouth or face, such as a medical mask. A mask is a worn item, not an expression, so a masked mouth gets `accessory:mask` and no `mood`. ## Custom styles This set is what DiceBear's own styles use, not a rule every style has to follow. A [custom style](https://www.dicebear.com/guides/create-an-avatar-style-with-figma/) can reuse these categories, add its own values, or define entirely different ones. As long as the grammar holds, you are free to describe your artwork in whatever way fits it best.