davatar-memoji

Deterministic memoji avatars for React. Give it a seed string — get back a consistent, expressive character from a catalog of 56 characters and 1,622 rendered expressions.

import { MemojiAvatar } from "davatar-memoji";

<MemojiAvatar seed="young woman with twin braids and round glasses" />

No API keys. No randomness. The same seed always returns the same character.

Install

npm install davatar-memoji

Peer dependency: react >= 17.

Usage

import { MemojiAvatar } from "davatar-memoji";

// Basic — deterministic from any string
<MemojiAvatar seed="[email protected]" size={128} />

// With expression
<MemojiAvatar seed="joshua" posture="thinking" size={96} />

// With appearance hints
<MemojiAvatar
  seed="young woman with twin braids"
  posture="party"
  genderPresentation="female"
  skinTone="black"
  age={25}
  size={128}
/>

Posture assets are served from a CDN by default — no setup required.

Expressions

20 built-in expressions:

happy laughing winking like thinking party heart-eye star-eye shocked sad angry victory kiss shush hugging sleeping crying scream rolling-eyes mind-blowing

<MemojiAvatar seed="alice" posture="happy" />
<MemojiAvatar seed="alice" posture="laughing" />
<MemojiAvatar seed="alice" posture="thinking" />

<MemojiAvatar> Props

| Prop | Type | Default | Description | | --- | --- | --- | --- | | seed | string | "davatar:memoji:default" | Any string. Descriptive text produces better matches. | | posture | string | "happy" | Expression key (see list above). | | size | number | 96 | Pixel dimensions. | | shape | "circle" \| "square" \| "none" | "circle" | Clip shape around the avatar. | | radius | number | 16 | Corner radius when shape="square". | | genderPresentation | "female" \| "male" | inferred | Hard hint for matching. | | skinTone | "black" \| "white" | inferred | Hard hint for matching. | | age | number | undefined | Nudges toward young-adult, adult, mature, or elder. | | description | string | undefined | Extra text to improve matching. | | tags | string[] | [] | Additional matching hints. | | baseAssetUrl | string | CDN | Override the base URL for posture assets. |

Standard <img> attributes (className, style, onClick, etc.) are also accepted.

matchMemoji()

Use the matching engine directly when you need the result before rendering:

import { matchMemoji } from "davatar-memoji";

const result = matchMemoji({
  seed: "woman in a hijab with green eyes",
  posture: "happy",
});

console.log(result.entry.name);              // "Ariana"
console.log(result.entry.description);       // "A warm young woman..."
console.log(result.selectedPosture.key);     // "happy"
console.log(result.selectedPosture.assetPath); // "female-ariana-black/01-happy.png"

MEMOJI_CATALOG

The full catalog array is exported for filtering, search UIs, or custom rendering:

import { MEMOJI_CATALOG } from "davatar-memoji";

console.log(MEMOJI_CATALOG.length); // 56 characters

Each entry includes name, description, hair/face/accessory metadata, searchable tags, and all posture variants.

Self-hosting assets

By default, posture images are loaded from unpkg. To self-host:

cp -R node_modules/davatar-memoji/assets public/memoji-assets

<MemojiAvatar seed="alice" baseAssetUrl="/memoji-assets" />

Credits

Memoji artwork by Moein Rabti (@m031n), licensed under CC BY 4.0. Assets have been reorganized and indexed for deterministic matching.

License

Code: MIT. Memoji assets: CC BY 4.0 (Moein Rabti).