OpenAvatar

OpenAvatar is a TypeScript SVG avatar generator with deterministic hashes, a demo page, and framework wrappers for React and Vue.

It generates head-focused SVG avatars from selectable parts, including background, hair, skin, expression, beard, and eyewear. The returned hash records the exact selected combination, so a saved avatar can be reproduced even if more options are added later.

Features

• Deterministic SVG avatar generation from any string or saved OpenAvatar hash.
• Stable snapshot hashes in the op-xxx-xxx:xxxx~category:value format.
• Transparent, solid color, and patterned backgrounds.
• circle, rounded-square, and square output shapes.
• React and Vue component entry points.
• Bilingual demo UI with random batches, option filters, hash loading, and integration examples.
• MIT licensed.

Install

Install from the official npm registry:

npm install open-avatar --registry=https://registry.npmjs.org/

If your npm registry already points to https://registry.npmjs.org/, the shorter command is enough:

npm install open-avatar

For local development in this repository:

npm install
npm run dev

Core API

Use the framework-neutral API when you need an SVG string, a data URL, or the exact snapshot hash to store in your own system:

import {
  AutoAvatar,
  generateAvatar,
  generateAvatarSvg,
  generateAvatarUrl,
  generateRandomAvatar,
  generateRandomAvatars,
  getAvatarParts,
  getTotalCombinations
} from "open-avatar";

const avatar = generateAvatar("user-42", {
  shape: "rounded-square",
  size: 160,
  title: "User 42"
});

console.log(avatar.hash);
console.log(avatar.svg);
console.log(avatar.url);
console.log(avatar.parts);

Render directly with an image tag:

const avatar = generateAvatar("user-42", { shape: "circle", size: 96 });

document.querySelector<HTMLImageElement>("#avatar")!.src = avatar.url;

Use AutoAvatar() when your app stores either a saved OpenAvatar hash, a remote image URL, or no user avatar value:

import { AutoAvatar } from "open-avatar";

const avatar = AutoAvatar("user-42", user.avatar, {
  shape: "circle",
  size: 96,
  title: "User 42"
});

document.querySelector<HTMLImageElement>("#avatar")!.src = avatar.src;

If user.avatar is a URL, avatar.src is that URL. If it is an OpenAvatar hash, avatar.src is a generated OpenAvatar image. If it is empty, "user-42" is used as the stable OpenAvatar hash, so the same user keeps the same generated avatar until they set an avatar value.

generateAvatar() returns:

type AvatarResult = {
  hash: string;
  svg: string;
  url: string;
  shape: "rounded-square" | "circle" | "square";
  parts: AvatarParts;
};

Hashes

OpenAvatar accepts any string as input. User-provided values are normalized into a short root hash, then the generated avatar returns a snapshot hash that stores the selected parts:

const draft = generateAvatar("customer:10086");

// Save this value after the user is satisfied.
const savedHash = draft.hash;

// Later, the same hash reproduces the same avatar.
const fixed = generateAvatar(savedHash);

Snapshot hashes are intentionally longer than a simple seed. They preserve the exact generated combination, so future option additions do not change existing saved avatars.

React

Install React in your app, then import the React entry:

npm install open-avatar react react-dom --registry=https://registry.npmjs.org/

import { Avatar } from "open-avatar/react";

export function UserAvatar() {
  return (
    <Avatar
      hash="op-user-42:1yf1e7~background:trianglify-blue~hair:bob-black~skin:peach~expression:happy-raisedExcited-smile~beard:none~clothing:shirtCrewNeck~eyewear:none"
      shape="circle"
      size={96}
      title="User avatar"
    />
  );
}

The existing Avatar component still renders only OpenAvatar hashes. For mixed stored values, use AutoAvatar:

import { AutoAvatar } from "open-avatar/react";

export function UserAvatar({ user }: { user: { id: string; avatar?: string | null } }) {
  return <AutoAvatar userIdOrName={user.id} avatar={user.avatar} shape="circle" size={96} />;
}

For a user-generated seed flow:

import { useMemo, useState } from "react";
import { generateAvatar } from "open-avatar";
import { Avatar } from "open-avatar/react";

export function AvatarPicker() {
  const [seed, setSeed] = useState("customer:10086");
  const avatar = useMemo(() => generateAvatar(seed), [seed]);

  return (
    <>
      <input value={seed} onChange={(event) => setSeed(event.target.value)} />
      <Avatar hash={avatar.hash} shape="rounded-square" size={120} />
      <code>{avatar.hash}</code>
    </>
  );
}

Vue

Install Vue in your app, then import the Vue entry:

npm install open-avatar vue --registry=https://registry.npmjs.org/

<script setup lang="ts">
import { Avatar } from "open-avatar/vue";
</script>

<template>
  <Avatar
    hash="op-user-42:1yf1e7~background:trianglify-blue~hair:bob-black~skin:peach~expression:happy-raisedExcited-smile~beard:none~clothing:shirtCrewNeck~eyewear:none"
    shape="rounded-square"
    :size="96"
    title="User avatar"
  />
</template>

The existing Avatar component still renders only OpenAvatar hashes. For mixed stored values, use AutoAvatar:

<script setup lang="ts">
import { AutoAvatar } from "open-avatar/vue";

defineProps<{
  user: {
    id: string;
    avatar?: string | null;
  };
}>();
</script>

<template>
  <AutoAvatar :user-id-or-name="user.id" :avatar="user.avatar" shape="circle" :size="96" />
</template>

For a user-generated seed flow:

<script setup lang="ts">
import { computed, ref } from "vue";
import { generateAvatar } from "open-avatar";
import { Avatar } from "open-avatar/vue";

const seed = ref("customer:10086");
const avatar = computed(() => generateAvatar(seed.value));
</script>

<template>
  <input v-model="seed" />
  <Avatar :hash="avatar.hash" shape="rounded-square" :size="120" />
  <code>{{ avatar.hash }}</code>
</template>

Demo

npm run dev

The demo includes:

• 9-avatar random preview grid.
• Hash loading and fixed avatar preview.
• Random-by-string workflow for choosing and saving a final hash.
• Option filters with localized display names.
• Light, dark, circular, rounded, square, navigation, menu, and dense stacked examples.
• Collapsible React/Vue integration notes.

Examples

Runnable examples live in examples/.

cd examples/react
npm install
npm run dev

cd examples/vue
npm install
npm run dev

The examples use Vite aliases to import this repository during local development. In an external project, install open-avatar and remove the local aliases.

Development

npm test
npm run build

Example builds:

cd examples/react
npm run build

cd examples/vue
npm run build

License

OpenAvatar is released under the MIT License. See LICENSE.

This project uses DiceBear Avataaars assets and APIs. See THIRD_PARTY_NOTICES.md for attribution details.