✨ 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.

• getContrast(hexColor: string): '#000000' | '#ffffff' Determines whether a dark (#000000) or light (#ffffff) foreground provides optimal contrast against any background hex color using standard YIQ perceived luminance.

• 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.