Avatars with a little character

Installation

One package for the React component, a plain JavaScript renderer, and the Croods collection. Import just the entry points you need.

npm install @illlustrations/avatars

React projects also need React 18.3.1 or 19.

More styles are on the way. Each one gets its own import path next to /croods, in the same package.

React

Import the component and the collection. Give it a seed—like a user ID—and it will pick a repeatable character for that style version.

import { Avatar } from '@illlustrations/avatars/react';
import { croods } from '@illlustrations/avatars/croods';

export function UserAvatar() {
  return (
    <Avatar
      assets={croods}
      seed="alex"
      size={64}
      shape="circle"
      background="#EDEDFF"
      title="Alex's avatar"
    />
  );
}

A different seed, a different possibility. Use title or an accessible label for meaningful avatars; otherwise the component is decorative.

Plain JavaScript

Use the core renderer for HTML, server-side generation, or another framework. The core and collection imports don’t load React or fetch artwork.

import { createAvatar } from '@illlustrations/avatars';
import { croods } from '@illlustrations/avatars/croods';

const avatar = createAvatar(croods, {
  seed: 'alex',
  size: 64,
  shape: 'circle',
  background: '#EDEDFF',
});

// Use an image in your page. No React required.
const image = document.createElement('img');
image.src = avatar.toDataUri();
image.alt = "Alex's avatar";
document.body.append(image);

For server-side output, use avatar.toString(). When inserting multiple inline SVG strings into one page, pass a unique idPrefix to each toString() call.

Seeds

A seed picks one combination from a frozen, versioned pool. The same seed and style version give the same avatar on the server, the client and every device, so you don’t need to store anything for generated profiles.

// Same seed, same avatar: on the server, the client and every device.
<Avatar assets={croods} seed={user.id} />

// Seeds pick head, face, outfit and glasses. Facial hair is opt-in.
<Avatar assets={croods} seed={user.id} selections={{ facialHair: 'beard' }} />

// Explicit selections always win over the seed.
<Avatar assets={croods} seed={user.id} selections={{ head: 'bun', face: 'happy' }} />

Resolution order: style defaults → seeded combination → explicit selections. Different seeds can land on the same avatar.

Playground

Start with a seed, then choose the hair, outfit, colors, and shape. The preview and code update together. Everything here runs in your browser.

<Avatar
  assets={croods}
  seed={"hello-world"}
  background="#EDEDFF"
  shape="rounded"
  size={128}
  title="Your avatar"
/>

51 parts, with their original placement built in. Explicit choices override the seed. Choose From seed to let the package pick again.

Parts

These are the only valid IDs for selections. Click one to copy it. Unknown IDs throw, so a typo never quietly renders the wrong person.

import { croods } from '@illlustrations/avatars/croods';

const hairstyles = croods.parts.head.map(({ id, name }) => ({
  value: id,
  label: name ?? id,
}));

Building tooling or prompting an AI? The same list is at /docs/parts.json.

Colors

Three layers, applied in order: a theme recolors everything, a palette swaps any artwork color, and the four colors roles always win.

Your brand colors, one per person

Pass a list and the seed picks one entry. Each person keeps their color everywhere, and a team gets your whole palette.

// One color, or a list: the seed picks one entry per person, every time.
<Avatar
  assets={croods}
  seed={user.id}
  colors={{ clothing: ['#254CE9', '#F76549', '#77E87B'], hair: ['original', '#272727'] }}
  background={['#DDE5FF', '#FFE6D2', '#D4EDE2']}
/>

Any artwork color

import { createAvatar } from '@illlustrations/avatars';
import { croods } from '@illlustrations/avatars/croods';

croods.palette;          // every artwork color: ['#000000', '#FF0000', '#FFFFFF', …]

const avatar = createAvatar(croods, {
  selections: { upperBody: 't-shirt-bag' },
  colors: { hair: '#254CE9' },          // roles first
  palette: { '#FF4B33': '#254CE9' },    // then any artwork color: here, the bag
});

avatar.sourceColors();   // artwork colors in this avatar's parts

• #000000Outlines (stroke role)
• #FF0000Hair and beard (hair role)
• #FFFFFFSkin (skin role), eye whites and teeth
• #313130Dark garments (clothing role)
• #FF4B33Bag on t-shirt-bag
• #FFE900Yellow garments (clothing role), shirt under the blazer
• #FF3F3FMouth and tongue
• #424242Mouth shadow
• #5DECFFDrool
• #F4F1EBDetail on shirt-1

A palette entry changes every use of that color. #FFFFFF is both skin and eye whites, so change skin with colors.skin. Unknown colors throw.

Examples

Chats, comments, leaderboards, onboarding and all the little places people show up. Every face below is the same <Avatar> component, with the props under each widget.

Looks good at every size.

<Avatar assets={croods} seed="alex" size={32} />
<Avatar assets={croods} seed="alex" size={64} />
<Avatar assets={croods} seed="alex" size={128} />

Recipes

Small, complete patterns for the places avatars usually end up.

import { Avatar } from '@illlustrations/avatars/react';
import { croods } from '@illlustrations/avatars/croods';

export function UserPhoto({ user }: { user: { id: string; name: string; photoUrl?: string } }) {
  if (user.photoUrl) return <img src={user.photoUrl} alt={user.name} width={40} height={40} />;
  // Seed with the user ID, not the name: names change, IDs don't.
  return <Avatar assets={croods} seed={user.id} size={40} shape="circle" title={user.name} />;
}

import { Avatar } from '@illlustrations/avatars/react';
import { croods } from '@illlustrations/avatars/croods';

export function Members({ members }: { members: { id: string; name: string }[] }) {
  return (
    <ul>
      {members.map(member => (
        <li key={member.id}>
          <Avatar assets={croods} seed={member.id} size={32} shape="circle" theme="neutral" background="#F2F0EE" />
          {member.name}
        </li>
      ))}
    </ul>
  );
}

'use client';
import { useState } from 'react';
import { createAvatar, type AvatarState } from '@illlustrations/avatars';
import { Avatar } from '@illlustrations/avatars/react';
import { croods } from '@illlustrations/avatars/croods';

export function AvatarPicker({ userId, onSave }: { userId: string; onSave: (state: AvatarState) => void }) {
  const [head, setHead] = useState<string>();
  const options = { seed: userId, selections: head ? { head } : {} };
  return (
    <>
      <Avatar assets={croods} {...options} size={120} title="Your avatar" />
      <select value={head ?? ''} onChange={event => setHead(event.target.value || undefined)}>
        <option value="">Surprise me</option>
        {croods.parts.head.map(part => <option key={part.id} value={part.id}>{part.name ?? part.id}</option>)}
      </select>
      <button onClick={() => onSave(createAvatar(croods, options).toJSON())}>Save</button>
    </>
  );
}

// Later, render the saved state:
// <Avatar assets={croods} selections={saved.selections} colors={saved.colors}
//   theme={saved.theme} background={saved.background} shape={saved.shape} />

import { createAvatar } from '@illlustrations/avatars';
import { croods } from '@illlustrations/avatars/croods';

export async function GET(_request: Request, { params }: { params: Promise<{ id: string }> }) {
  const { id } = await params;
  const svg = createAvatar(croods, { seed: id, size: 256, shape: 'circle' }).toString({ title: 'Avatar' });
  return new Response(svg, {
    headers: { 'Content-Type': 'image/svg+xml', 'Cache-Control': 'public, max-age=86400' },
  });
}