Deterministic 3D SVG Avatar Generator for JavaScript, React, and Vue - Planet Avatar

Authorvikingmute

Last UpdateMay 21, 2026

LicenseMIT

Features:

Return self-contained SVG markup.
Create image-ready data URIs.
Mount avatars into existing elements.
Works with vanilla JavaScript, React, and Vue.
7 unique planet styles.
Customize colors, rings, backgrounds, and size.
Accessible titles for meaningful avatars.

Use Cases:

Render unique avatar images for user accounts where profile photos are unavailable.
Display consistent placeholder visuals in activity feeds, comment threads, or notification lists.
Populate team or member directories with generated identity images during data loading.
Generate stable thumbnail images for product cards, seed-based demos, or design prototypes.

How to use it:

1. Install planet-avatar with NPM and import createPlanetAvatar into your JS project.

# NPM
$ npm install planet-avatar

import { createPlanetAvatar } from 'planet-avatar';

2. Generate a stable SVG avatar and insert it into a target element. The seed should come from a stable identity value such as a user ID, username, email hash, or database key.

const avatarTarget = document.querySelector('#account-avatar');
const avatarSvg = createPlanetAvatar({
  seed: 'csscript',
  size: 128,
  variant: 'orbit',
  rings: true,
  title: 'Customer 10017 avatar'
});
avatarTarget.innerHTML = avatarSvg;

3. Convert the generated SVG into a value that works as an image source. This can be useful if your profile image requires an img element instead of inline SVG markup.

profileImage.src = createPlanetAvatarDataUri({
  seed: 'csscript',
  size: 96,
  title: 'Member avatar'
});

4. Render the SVG directly into an existing DOM element.

// Render the SVG into an existing DOM element.
mountPlanetAvatar(cardAvatar, {
  seed: 'cssscript',
  size: 72,
  variant: 'auto',
  title: 'Support agent avatar'
});

5. Teams that want a specific visual style across all avatars can pin the variant option.

// Log all available variant names
console.log(VARIANT_NAMES);
// ['void', 'drift', 'mira', 'flux', 'luna', 'orbit', 'sol']
// Force all avatars to the 'sol' variant
const svg = createPlanetAvatar({
  seed: 'cssscript',
  size: 128,
  variant: 'sol'
});

6. Apply a custom palette. The custom palette accepts an array of CSS color strings and falls back to the active variant when some palette slots remain empty.

const brandedAvatar = createPlanetAvatar({
  seed: 'cssscript',
  size: 144,
  variant: 'flux',
  palette: ['#101828', '#4f46e5', '#a5b4fc', '#312e81'],
  background: '#f8fafc',
  rings: false,
  title: 'Billing user avatar'
});

Donfiguration options

seed (string | number): Required identity input. The same seed and options produce the same SVG output.
size (number): Sets the SVG width and height. The default size is 128.
variant ('auto' | 'void' | 'drift' | 'mira' | 'flux' | 'luna' | 'orbit' | 'sol'): Controls the planet style. The auto value selects a stable style from the seed.
palette ('auto' | string[]): Sets custom colors for the generated planet. Missing custom colors fall back to the active variant palette.
rings (boolean | 'auto'): Forces rings, disables rings, or lets the selected variant and seed decide.
background ('transparent' | string): Sets the SVG background fill. Use transparent or a valid CSS color string.
title (string): Adds an accessible SVG title. The generated SVG uses decorative ARIA behavior when no title exists.

API methods

import {
  createPlanetAvatar,
  createPlanetAvatarDataUri,
  mountPlanetAvatar,
  VARIANT_NAMES,
  VARIANTS
} from 'planet-avatar';
// Return a complete SVG string.
const inlineSvg = createPlanetAvatar({
  seed: 'invoice-owner-300',
  size: 128,
  variant: 'sol',
  title: 'Invoice owner avatar'
});
// Return a data:image/svg+xml URI for img tags or CSS usage.
const imageSource = createPlanetAvatarDataUri({
  seed: 'project-manager-18',
  size: 96,
  variant: 'drift'
});
// Render the generated SVG into an existing DOM element.
const avatarSlot = document.querySelector('#project-avatar');
mountPlanetAvatar(avatarSlot, {
  seed: 'project-alpha',
  size: 112,
  rings: 'auto'
});
// Read the available variant names for UI controls.
console.log(VARIANT_NAMES);
// Read the full variant data for custom tooling.
console.log(VARIANTS);

React component integration

The React adapter exports a PlanetAvatar component and a usePlanetAvatar hook. The component handles rendering directly. The hook returns the raw SVG string for cases where you need access to the markup in component logic.

Import from planet-avatar/react and pass the same options you would use with the core function.

import { PlanetAvatar, usePlanetAvatar } from 'planet-avatar/react';
function UserCard({ userId }: { userId: string }) {
  // Hook returns the SVG string for use in logic
  const svg = usePlanetAvatar({ seed: userId, size: 80 });
  return (
    <div className="user-card">
      {/* Component renders the avatar directly */}
      <PlanetAvatar
        seed={userId}
        size={80}
        variant="luna"
        title={`Avatar for ${userId}`}
      />
      <span>SVG length: {svg.length} chars</span>
    </div>
  );
}

Vue component integration

The Vue adapter exports a PlanetAvatar component and a usePlanetAvatar composable. Import from planet-avatar/vue and use the component inside any template.

<script setup lang="ts">
import { PlanetAvatar } from 'planet-avatar/vue';
const props = defineProps<{ userId: string }>();
</script>
<template>
  <div class="member-card">
    <PlanetAvatar
-seed="props.userId"
-size="96"
      variant="drift"
-title="`Avatar for ${props.userId}`"
    />
  </div>
</template>

Alternatives:

FAQs:

Q: Can I use Planet Avatar for the same user across multiple pages?
A: Yes. Use the same seed and the same options on every page. The generated SVG remains stable for that identity.

Q: Why does my avatar change after each render?
A: The seed likely changes between renders. Use a permanent user ID, email hash, username, or database key.

Q: How should I handle accessibility for generated avatars?
A: Pass a title when the avatar conveys identity or content. Leave the title empty when the avatar only decorates the interface.

Deterministic 3D SVG Avatar Generator for JavaScript, React, and Vue – Planet Avatar