pinecone-avatars

A customizable React avatar picker library with 60+ unique combinations. Generate fun, SVG-based avatars with different backgrounds, skin tones, hairstyles, expressions, and outfits.

!npm
!license
!bundle size

!Preview

Live Demo

Features

- 8 background colors
- 1 skin tone
- 27 hairstyles
- 13 expressions
- 9 t-shirt colors
- Fully typed with TypeScript
- Export to SVG, Base64, or PNG
- Zero dependencies (only React peer dep)
- Works with Next.js, Vite, Create React App

Framework Compatibility

| Framework | Support |
|-----------|---------|
| Next.js (App Router) | Full support |
| Next.js (Pages Router) | Full support |
| Vite + React | Full support |
| Create React App | Full support |
| Remix | Full support |

> Note: generatePngBase64(), downloadSvg(), and downloadPng() require browser environment. In Next.js, call these only on the client side.

Installation

``bash
npm install pinecone-avatars
`

`bash
yarn add pinecone-avatars
`

`bash
pnpm add pinecone-avatars
`

`bash
bun add pinecone-avatars
`

Quick Start

`tsx
import { Avatar } from 'pinecone-avatars';

function App() {
return ;
}
`

Usage

$3

`tsx
import { Avatar } from 'pinecone-avatars';


`

$3

`tsx
import { Avatar } from 'pinecone-avatars';

size={200}
background="babyBlue"
skin="softPeach"
tshirt="orange"
expression="happy"
hair="shortBuzz"
/>
`

$3

`tsx
import { Avatar, generateRandomConfig } from 'pinecone-avatars';


`

$3

Interactive UI for selecting avatar options:

`tsx
import { AvatarPicker } from 'pinecone-avatars';

function App() {
const handleChange = (config) => {
console.log('Avatar config:', config);
};

return ;
}
`

$3

`tsx
import {
generateSvg,
generateBase64,
generatePngBase64,
downloadSvg,
downloadPng
} from 'pinecone-avatars';

const config = {
background: 'babyBlue',
skin: 'softPeach',
tshirt: 'orange',
expression: 'happy',
hair: 'shortBuzz'
};

// Get full SVG string
const svgString = generateSvg(config);

// Get base64 SVG data URL
const base64Svg = generateBase64(config);

// Use in img tag


// Get base64 PNG (browser only)
const base64Png = await generatePngBase64(config, 512);

// Download as SVG file (browser only)
downloadSvg(config, 'my-avatar.svg');

// Download as PNG file (browser only)
await downloadPng(config, 512, 'my-avatar.png');
`

Next.js Example

`tsx
// app/page.tsx (App Router)
import { Avatar, generateRandomConfig } from 'pinecone-avatars';

export default function Page() {
return ;
}
`

`tsx
// app/picker/page.tsx (App Router - AvatarPicker works directly, has "use client" built-in)
import { AvatarPicker } from 'pinecone-avatars';

export default function PickerPage() {
return console.log(config)} />;
}
`

`tsx
// Client-side export (App Router)
"use client";

import { downloadPng } from 'pinecone-avatars';

export function DownloadButton({ config }) {
return (
downloadPng(config, 512, 'avatar.png')}>
Download PNG

);
}
`

API Reference

$3

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| size | number | 200 | Avatar size in pixels |
| background | BackgroundType | 'babyBlue' | Background color |
| skin | SkinType | 'softPeach' | Skin tone |
| tshirt | TshirtType | 'orange' | T-shirt color |
| expression | ExpressionType | 'happy' | Facial expression |
| hair | HairType | 'shortBuzz' | Hairstyle |
| className | string | - | CSS class name |
| style | CSSProperties | - | Inline styles |

$3

| Prop | Type | Description |
|------|------|-------------|
| value | AvatarConfig | Controlled value |
| onChange | (config: AvatarConfig) => void | Change callback |
| className | string | CSS class name |

$3

| Function | Description |
|----------|-------------|
| generateRandomConfig() | Returns a random AvatarConfig |
| generateSvg(config?, size?) | Returns SVG string |
| generateBase64(config?, size?) | Returns base64 SVG data URL |
| generatePngBase64(config?, size?) | Returns base64 PNG data URL (async, browser only) |
| downloadSvg(config?, filename?) | Downloads SVG file (browser only) |
| downloadPng(config?, size?, filename?) | Downloads PNG file (async, browser only) |

Available Options

$3

babyBlue | coralRed | darkGray | lightGray | mintGreen | pastelGreen | peach | softPink

$3

softPeach

$3

amber | blue | charcoal | green | orange | pink | raspberry | white | yellow

$3

angry | focused | furious | happy | laughing | sad | shocked | sideGlance | sleepy | starry | suspicious | tired | worried

$3

afroPuffs | asymmetricBuns | bob | bobSidePart | bowlCut | braids | bunnyEars | curlyHeadband | curlyMessy | curlyPigtails | curlyPuff | fullCurly | longAfro | longPeak | longStraight | messyArtistic | pigtailBuns | shortBuns | shortBuzz | shortCurly | sideBangs | spaceBuns | spikyEarmuffs | tinyBun | topKnot | wavyCenterPart | wavyPuffs

TypeScript

Full TypeScript support with exported types:

`tsx
import type {
AvatarConfig,
AvatarProps,
AvatarPickerProps,
BackgroundType,
SkinType,
TshirtType,
ExpressionType,
HairType
} from 'pinecone-avatars';
`

Constants

Access all available options as arrays:

`tsx
import {
BACKGROUNDS,
SKINS,
TSHIRTS,
EXPRESSIONS,
HAIRS
} from 'pinecone-avatars';

console.log(BACKGROUNDS); // ['babyBlue', 'coralRed', ...]
console.log(HAIRS); // ['afroPuffs', 'asymmetricBuns', ...]
``

About

Built with love by Pinecone - A software development company based in Mongolia.

License

MIT