@usespaceui/avatars

Generative Deterministic SVG avatar generator for your UI projects. A unique generative avatar for every seed.

Preview • Source Code • SpaceUI.one

---

✨ Overview

@usespaceui/avatars is a free, zero-dependency React library that generates beautiful, deterministic SVG avatars. The same seed always produces the same avatar, with no stored images and no network calls.

---

🌐 HTTP API Live Demo

You can generate avatars without installing anything by using the free REST API endpoint. It supports svg, png, webp and json outputs.

<!-- Clean URL Route -->
<img src="https://avatars.spaceui.one/v1/pebble/orion.svg" alt="Orion" />

<!-- Query Parameters Route -->
<img src="https://avatars.spaceui.one/v1?name=jupiter&variant=lumina&format=webp" alt="Jupiter" />

---

📦 Installation

pnpm add @usespaceui/avatars
# or
npm install @usespaceui/avatars
# or
yarn add @usespaceui/avatars

Zero dependencies.

---

🚀 Usage

React Component

import { Avatar, AvatarVariant } from '@usespaceui/avatars'

export default function Demo() {
  return <Avatar name="Sirius" variant={AvatarVariant.triton} size={64} circle animate />
}

Set animate={false} whenever motion should be disabled for a specific context.

Core API (Framework-agnostic)

You can generate the raw SVG markup or JSON data directly for server environments or vanilla JS:

import { createAvatar, AvatarOutputFormat } from '@usespaceui/avatars'

// Generate raw SVG string
const svg = createAvatar({ name: 'sirius', variant: 'gradient', size: 256 })

// Generate JSON metadata and structured data
const avatarJson = createAvatar({
  name: 'vega',
  variant: 'pebble',
  format: AvatarOutputFormat.json,
})

name is the deterministic identity. createAvatar() and <Avatar /> use the stable default name when it is omitted or empty. A variant can be an individual style or a family name: gradient/gradients, fluid/fluids, classic/classics, or paletteless.

---

⚙️ React Props

Prop	Type	Default	Description
name	string	"Space UI"	Deterministic avatar identity seed.
variant	AvatarVariant | AvatarFamily | "all"	"pebble"	The visual family / style of the avatar, or "all" for a random deterministic variant across all styles.
size	number	64	Rendered size in pixels.
circle	boolean	false	If true, clips the avatar to a full circle (otherwise a full rectangle).
colors	[string, string, string, string, string]	–	Exactly 5 colors to use. If omitted, a harmonious palette is generated.
effect	AvatarEffect	"none"	Optional post-processing effect (none or noise).
animate	boolean	false	Whether to animate the avatar.
className	string	–	Optional CSS class applied to the wrapper span element.

Note: Custom palettes must contain exactly five hexadecimal colors. Unsupported effects and animation combinations are safely disabled in the returned output metadata.

---

🧰 Utilities Included

• createAvatar(options: CreateAvatarOptions): string | AvatarJson Core deterministic generation engine. Takes a configuration object (name, variant, colors, etc.) and returns either an SVG string or a structured JSON object.

• resolveVariant(name: string, variant?: string): AvatarVariant Safely resolves a generic family name (e.g. "classics", "gradients"), "all", or any variant string into a concrete AvatarVariant.

• getAvatarDetails(variant: AvatarVariant): AvatarDetails Retrieves capabilities metadata (e.g. if it supports animation or custom colors) for a specific variant.

• getAllAvatarDetails(): AvatarDetails[] Returns metadata for all available variants.

• getFamilyVariants(family: AvatarFamily): AvatarVariant[] Groups and returns all variants belonging to a specific family or "all".

• isAnimateActive(variant: AvatarVariant, animate?: boolean): boolean Helper to check if motion is allowed, returning false if the variant doesn't support animation.

---

📦 Related Packages

Package	Description
@usespaceui/sounds	UI sound effects and audio interactions
@usespaceui/squircle	Figma-style corner smoothing (Apple squircles)

---

🪪 License

MIT — Free for commercial and personal use.

---

📚 Resources

• 🔍 Explore the avatars & Playground
• 📖 Full Documentation
• 🌍 Space UI Official Site

---

🛠 Maintenance

If you find a bug or have a feature request, please open an issue on GitHub. Engine internals are intentionally not part of the public API.

---

Maintained by the Space UI Team