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

Documentation

Start with React, then configure the generated SVG. The complete package and HTTP references are kept separate.@usespaceui/avatars

Overview

Every avatar is a deterministic SVG generated from a name. The same value always yields the same avatar. There are no stored images and no network request at render time.

1 Install

Add the package to a React,Next.js,Remix, or any otherVanilla JavaScript project.

2 Render

Use <Avatar /> or createAvatar()with an optional name.

3 Configure

Choose a variant, colors, shape, and motion preferences to match your brand.

Installation

Install with your package manager of choice. React 18 or newer is the only peer dependency.

Installation

bun add @usespaceui/avatars

Quick start

Import the component and give it a name. Omit it to render the stable default avatar. The same name always renders the same shape or gradient, so a user id or email is a stable avatar with nothing to store.

import { Avatar } from '@usespaceui/avatars/react';
export function AvatarExample({ user }) {
  return <Avatar name="Space UI" size={64} />;
}

React props

PropTypeDescription

name

string

Deterministic identity. Omit it or pass an empty string to use the stable default avatar.

Default: Space UI

size

number

Rendered size in pixels.

Default: 64

variant

AvatarVariant

Render family / style.

Default: "triton"

circle

boolean

If true, clips the avatar to a full circle. Defaults to false (full rectangle).

Default: false

colors

[string, string, string, string, string]

Exactly five hexadecimal colors. The name still drives the layout, so each avatar stays unique but on-brand.

effect

"none""noise"

Apply post-processing effects. Only works on Gradient variants.

Default: "none"

animate

boolean

Animates the avatar continuously. Works on Gradients, Fluids, and some Classics (invader). Only supported when effect is "none".

Default: false

className

string

Standard React className, applied to the wrapper.

Sizes & shapes

size scales the avatar. By default, it renders as a hard square. Pass circle or circle={true}to clip it into a full circle.

circle

default (rectangle)

<Avatar name="Space UI" size={84} circle /> // circle
<Avatar name="Space UI" size={84} />        // default (rectangle)
// Procedural fluids
<Avatar name="Space UI" variant="splash" size={84} />
// Classics
<Avatar name="Space UI" variant="pebble" size={84} />

Choose a variant

Beyond the classic gradient mesh, the @usespaceui/avatars package groups its 21 variants into four visual families. Choose a concrete variant when you need a fixed look; pass a family when you want a deterministic choice within that family.

gradient

lumina

shaula

singularity

triton

solar-flare

titan

glass

fluid

splash

animals

astronaut

ghost

bot

glitch

classic

pebble

invader

grunge

bored

doodle

squiggle

paletteless

critter

kendo

Custom colors

By default the palette is derived from the name via color-harmony rules. Pass colors to use your own palette instead, brand colors, a product theme, anything. The name still drives the layout (and rotates which color leads), so every avatar stays unique while staying on-brand. Hex in, # optional. You must pass exactly 5 colors.

// Your brand palette instead of the name-derived harmony.
<Avatar
  name="Space UI"
  colors={["#4f46e5", "#06b6d4", "#ec4899", "#8b5cf6", "#14b8a6"]}
/>

Explore the package API

The component covers everyday usage. These helpers are for variant pickers, capability-aware controls, and other programmatic integrations. Each one is documented with its exact return value in the API reference.

Use AvatarFamily and getFamilyVariants(family) to build a picker or choose a deterministic family.

Next: API reference

Need the complete list of constants, TypeScript types, return values, and REST routes? Continue to the package and HTTP API reference. The package creates SVG or JSON only; PNG and WebP are available through the HTTP API.