Kodama 木魅

Tiny spirits, born from strings. Always alive.

Documentation · API · npm

Kodama is an open-source avatar system that generates unique, animated characters from any string. Unlike traditional avatars, every Kodama is fully animated — blinking, floating, glancing — right out of the box. 145,152 unique combinations ensure no two avatars look alike.

# bun
bun install kodama-id

# npm
npm install kodama-id

# pnpm
pnpm add kodama-id

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" />

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, 4 eyebrow types, 7 mouths, 2 cheek options, 3 accessories, 16 colors, and 9 rotations.

All animations are CSS-based and injected on demand — combine freely.

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

happy · surprised · sleepy · cool · cheeky

Three clipping shapes — circle, squircle, square — and four 3D depth levels — none, subtle, medium, dramatic.

Replace the default palette with your own gradient pairs.

<Kodama
  name="user"
  gradients={[
    { from: "#667EEA", to: "#764BA2" },
    { from: "#F093FB", to: "#F5576C" },
  ]}
/>

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

For interactive examples, a live playground, and the full API reference, visit kodama.sh.

Kodama is licensed under the MIT License.