Is @usespaceui/avatars free?

Yes. It is free and open source under the MIT license, for commercial or personal projects, with no attribution required.

How are the avatars generated?

Each avatar is derived deterministically from its seed via a hashing function, so the same seed always yields the same result. Nothing is stored and no network request is made.

Can it render anything besides gradients?

Yes. Choose from gradient, fluid, classic, and paletteless families. Every variant renders deterministically from its seed.

Does it make network requests?

No. Avatars render locally as self-contained SVGs. Nothing is uploaded, sent to a remote service, or stored.

Can I use it in Vue, Solid, Svelte or vanilla JS?

Yes. Although the React component is the most popular entry point, the underlying @usespaceui/avatars library provides a framework-agnostic createAvatar function that works in any JavaScript environment. It returns a self-contained SVG string or JSON payload.

Space UI

SDK & Types

Everything you need to interact with the package programmatically.

SDK

1. Package Installation

The @usespaceui/avatars package renders SVG markup synchronously. It has no raster encoder: PNG and WebP are provided by the HTTP API.

Installation

bun add @usespaceui/avatars

React

2. React Component Usage

Import <Avatar /> to render SVG avatars directly as React JSX elements.

import { AvatarVariant, AvatarEffect } from '@usespaceui/avatars'
import { Avatar } from '@usespaceui/avatars/react';
export function UserProfile({ username }: { username: string }) {
  return (
    <Avatar 
      name="Space UI"
      variant={AvatarVariant.pebble} 
      size={64} 
      circle={true} 
      effect={AvatarEffect.none}
    />
  );
}

Constants

3. Runtime Object Constants

Use exported runtime object constants (AvatarFamily AvatarEffect, AvatarVariant, AvatarOutputFormat) for clean dot-notation autocompletion. They are values, not functions, so they do not return anything. AvatarOutputFormat applies only to package output: SVG or JSON.

import { AvatarFamily, AvatarEffect, AvatarVariant, AvatarOutputFormat, DEFAULT_AVATAR_VARIANT } from '@usespaceui/avatars';
// Runtime constants — use these instead of hand-written strings.
console.log(AvatarFamily.gradient);     // "gradient"
console.log(AvatarEffect.noise);      // "noise"
console.log(AvatarVariant.triton);    // "triton"
console.log(DEFAULT_AVATAR_VARIANT);  // "pebble"
// Package output only: "svg" or "json". PNG/WebP are HTTP API formats.
console.log(AvatarOutputFormat.json); // "json"

TypeScript

4. TypeScript Types

TypeScript types such as AvatarProps, CreateAvatarOptions, AvatarColors, AvatarJson, and AvatarDetails only exist during type checking and will not be compiled into your bundle.

import type { CreateAvatarOptions, AvatarColors, AvatarJson, AvatarDetails } from '@usespaceui/avatars';
import type { AvatarProps } from '@usespaceui/avatars/react';
/*
  AvatarProps: Props for the React component
  CreateAvatarOptions: Options for the createAvatar function
// AvatarColors: A 5-color tuple for custom palettes
// AvatarJson: JSON output format containing SVG string and data URIs
// AvatarDetails: Metadata about a variant's capabilities
*/

Generator

5. Pure TS createAvatar(options) Function

createAvatar(options) generates deterministic avatar output. Set format: AvatarOutputFormat.svg (default) to return an SVG string, or format: AvatarOutputFormat.json to return a structured JSON object with dataURIs.

import { createAvatar, AvatarVariant, AvatarEffect, AvatarOutputFormat } from '@usespaceui/avatars';
// 1. Zero arguments -> stable "default" avatar
const defaultSvg = createAvatar();
// 2. SVG string output
const svgMarkup = createAvatar({
  name: "alex",
  variant: AvatarVariant.triton,
  size: 256,
  effect: AvatarEffect.none,
});
// 3. Structured JSON payload with an SVG Data URI
const jsonPayload = createAvatar({
  name: "alex",
  variant: AvatarVariant.pebble,
  format: AvatarOutputFormat.json,
});

Functions

6. Resolving Variants

resolveVariant turns a variant or family into one concrete variant. Use getFamilyVariants to list the variants belonging to a specific family.

FunctionReturn TypeDescription

resolveVariant(value)AvatarVariantResolves a concrete variant or a deterministic variant from a family.

getFamilyVariants(family)AvatarVariant[]Lists the concrete variants in one family; an unknown family gives an empty list.

import { AvatarFamily, resolveVariant, getFamilyVariants } from '@usespaceui/avatars';
// Get all concrete variants in a family
const gradients = getFamilyVariants(AvatarFamily.gradient);
console.log(gradients); 
// ["lumina","shaula","singularity","triton","solar-flare","titan","glass"]
// Resolve a string like "alex" to a deterministic variant within a family
const selectedVariant = resolveVariant("alex", AvatarFamily.gradient);
console.log(selectedVariant); // "triton" (for example)

Functions

7. Inspecting Capabilities

Metadata functions expose the catalog and capabilities without duplicating constants.

FunctionReturn TypeDescription

getAvatarDetails(variant)AvatarDetails | undefinedReturns one capability record; an unknown variant returns undefined.

getAllAvatarDetails()AvatarDetails[]Returns detached capability records for every variant.

import { AvatarVariant, getAvatarDetails, getAllAvatarDetails } from '@usespaceui/avatars';
// Inspect a specific variant's capabilities
const triton = getAvatarDetails(AvatarVariant.triton);
/*
{
  id: "triton",
  family: "gradient",
  supportsAnimate: true,
  supportedEffects: ["none", "noise"],
  animatedEffects: ["none"],
  supportsColors: true
}
*/
// Retrieve the full catalog of all variants
const catalog = getAllAvatarDetails();
console.log(catalog.length); // 21
// catalog[0] -> { id: "triton", family: "gradient", ... }

Functions

8. Animation Capability Check

Verify if a variant supports animation for a particular effect dynamically.

FunctionReturn TypeDescription

isAnimateActive(variant, effect)booleanTrue only when animation can run for that variant and effect combination.

import { AvatarVariant, AvatarEffect, isAnimateActive } from '@usespaceui/avatars';
// Check if a combination of variant and effect supports animation
// (Animation is currently ONLY active when effect === "none")
const canAnimate = isAnimateActive(AvatarVariant.triton, AvatarEffect.none);