A customizable React avatar picker library with 60+ unique combinations
npm install pinecone-avatarsA customizable React avatar picker library with 60+ unique combinations. Generate fun, SVG-based avatars with different backgrounds, skin tones, hairstyles, expressions, and outfits.
- 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 | 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.
``bash`
npm install pinecone-avatars
`bash`
yarn add pinecone-avatars
`bash`
pnpm add pinecone-avatars
`bash`
bun add pinecone-avatars
`tsx
import { Avatar } from 'pinecone-avatars';
function App() {
return
}
`
`tsx
import { Avatar } from 'pinecone-avatars';
`
`tsx
import { Avatar } from 'pinecone-avatars';
background="babyBlue"
skin="softPeach"
tshirt="orange"
expression="happy"
hair="shortBuzz"
/>
`
`tsx
import { Avatar, generateRandomConfig } from 'pinecone-avatars';
`
Interactive UI for selecting avatar options:
`tsx
import { AvatarPicker } from 'pinecone-avatars';
function App() {
const handleChange = (config) => {
console.log('Avatar config:', config);
};
return
}
`
`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');
`
`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
}
`
`tsx
// Client-side export (App Router)
"use client";
import { downloadPng } from 'pinecone-avatars';
export function DownloadButton({ config }) {
return (
);
}
`
| 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 |
| Prop | Type | Description |
|------|------|-------------|
| value | AvatarConfig | Controlled value |onChange
| | (config: AvatarConfig) => void | Change callback |className
| | string | CSS class name |
| 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) |
babyBlue | coralRed | darkGray | lightGray | mintGreen | pastelGreen | peach | softPink
softPeach
amber | blue | charcoal | green | orange | pink | raspberry | white | yellow
angry | focused | furious | happy | laughing | sad | shocked | sideGlance | sleepy | starry | suspicious | tired | worried
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
Full TypeScript support with exported types:
`tsx`
import type {
AvatarConfig,
AvatarProps,
AvatarPickerProps,
BackgroundType,
SkinType,
TshirtType,
ExpressionType,
HairType
} from 'pinecone-avatars';
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', ...]
``
Built with love by Pinecone - A software development company based in Mongolia.
MIT