Tiny spirits, born from strings.
Always alive.

Try it out — enter a name, adjust the options, and watch the avatar update live.
Drop it into your project with the API or React component.

• Depthnone - subtle - medium - dramatic
• Moodnone - happy - surprised - sleepy - cool - cheeky
• Animationsblink - float - sway - eyeWander - eyebrowBounce - glance - entrance

API

Generate avatars as SVG over HTTP. The name is the URL path — all options go in the query string.

<img src="https://api.kodama.sh/kodama?animations=blink" />

React

Import the Kodama component and pass a name string. Props match the API parameters.

import { Kodama } from "kodama-id/react";

<Kodama
  name="kodama"
  size={48}
  animations={["blink"]}
/>

Avatars are derived from a hash of the input string — the same name always produces the same face. Fully deterministic, with nothing stored or fetched.

Faces are assembled from 6 eye styles x 4 eyebrow types x 7 mouths x 2 cheek options x 3 accessories x 16 colors x 9 rotations.

• Eyesround - cross - line - curved - wink - heart
• Mouthssmile - grin - o - cat - tongue - smirk - flat
• Eyebrowsarched - flat - raised - none
• Cheeksblush - none
• Accessoriesglasses - sunglasses - none

Sixteen soft pastel gradients with radial rendering for a subtle 3D appearance.
Pass in a custom gradients array to use your own palette.

Variants are pluggable visual styles. Each variant defines its own set of props — moods, animations, detail levels, and more. Pass a variant factory directly or pre-configure it with a descriptor.

import { faces } from "kodama-id/variants";

// Pass directly — configure via props
<Kodama name="luna" variant={faces} background="solid" mood="happy" />

// Or pre-configure with a descriptor
<Kodama name="luna" variant={faces({ background: "solid", detailLevel: "full" })} />

Set a mood to give the avatar a specific expression, regardless of the generated features.

<Kodama name="user" mood="happy" />
<Kodama name="user" mood="cool" />

Pass an animations array to bring avatars to life. All animations are CSS-based and injected on demand — combine freely. Pass a string for defaults, or an object with type, delay, and duration for custom timing.

<Kodama
  name="sprite"
  animations={["blink", "float", "sway", "eyeWander"]}
/>

// With custom timing
<Kodama
  name="sprite"
  animations={[
    "blink",
    { type: "float", duration: 4, delay: 0.5 },
  ]}
/>

Choose between a circle, squircle, or square clip for the avatar.

<Kodama name="user" shape="circle" />
<Kodama name="user" shape="squircle" />
<Kodama name="user" shape="square" />

Four depth levels for CSS 3D perspective transforms. The face tilts based on the deterministic rotation. In React, the face flattens on hover when interactive is enabled.

<Kodama name="user" depth="dramatic" />

Feature visibility automatically adapts to size. Smaller avatars show fewer features for clarity. Override with the detailLevel prop.

Replace the default palette with your own gradient pairs via the gradients prop. The API accepts hex pairs like E8D5F5-C7A4E0,FFE0D0-FFB899.

const brand = [
  { from: "#667EEA", to: "#764BA2" },
  { from: "#F093FB", to: "#F5576C" },
];

<Kodama name="user" gradients={brand} />

Props and API params share the same names. In the API, name is the URL path — all others are query params.

Global

Faces