Version 1.0.0 · React 18 and 19 · zero runtime dependencies.
npm install react-avatar-kitimport { Avatar } from 'react-avatar-kit'
<Avatar seed="ada@example.com" size={64} />That is the whole integration. seed can be a user id, an email, a username or any
stable string; the same seed always renders the same avatar, on the server and in the
browser. size accepts a number (pixels) or any CSS length.
import { Avatar } from 'react-avatar-kit'
<Avatar seed="ada@example.com" size={96} shape="rounded" alt="Ada Lovelace" />Renders a single, self-contained <svg>. It uses no hooks, no context and no
client-only APIs, so it is valid in a React Server Component, in react-dom/server
and in a plain React 18/19 client tree.
interface AvatarProps extends AvatarOptions {
config?: AvatarConfig
size?: number | string
alt?: string
title?: string
className?: string
style?: CSSProperties
id?: string
}| Prop | Type | Default | Meaning |
|---|---|---|---|
seed |
string |
"default" |
Deterministic seed. Any stable string. |
config |
AvatarConfig |
– | A full config from createAvatar(). Explicit props win over it. |
size |
number | string |
64 |
Width and height. Numbers are pixels; strings may be any CSS length. |
shape |
"circle" | "rounded" | "square" | "none" |
"circle" |
Corner treatment of the avatar canvas. |
alt |
string |
– | Accessible name. When present the SVG is role="img" with a <title>; when absent the avatar is decorative (aria-hidden="true"). |
title |
string |
– | Native SVG tooltip, independent of alt. |
className |
string |
– | Passed to the root <svg>. |
style |
CSSProperties |
– | Merged onto the root <svg> after width/height. |
id |
string |
– | DOM id for the root <svg>. |
Every field of AvatarOptions may also be passed directly as a prop, so
<Avatar seed="ada" hair="mohawk" shirt="hoodie" /> works.
function Avatar(props: AvatarProps): ReactElementfunction createAvatar(input?: string | AvatarOptions): AvatarConfigcreateAvatar("ada@example.com")→ the deterministic avatar for that seed.createAvatar({ seed: "ada", hair: "mohawk" })→ the same avatar with one override.createAvatar()→ a random avatar. It returns its generatedseed, so you can store the result and render it again later.
The result is a plain, JSON-serialisable object that can be stored in a database, put in a cache, or sent over the wire. Spread it into the component:
const config = createAvatar('ada@example.com')
<Avatar {...config} size={96} />interface AvatarOptions {
seed?: string
palette?: PaletteName
background?: AvatarColor | AvatarGradient
skin?: AvatarColor
hair?: HairStyle
hairColor?: AvatarColor
highlight?: boolean
hat?: HatStyle
hatColor?: AvatarColor
ears?: 'small' | 'big'
eyes?: EyeStyle
brows?: BrowStyle
glasses?: GlassesStyle
nose?: NoseStyle
mouth?: MouthStyle
shirt?: ShirtStyle
shirtColor?: AvatarColor
shape?: Shape
}| Option | Type | Default | Notes |
|---|---|---|---|
seed |
string |
"default" |
Drives every field that is not overridden. |
palette |
"default" | "pastel" | "vivid" | "mono" | "earth" | "neon" |
"default" |
Colour family used for generated colours. Explicit colours always win. |
background |
string | AvatarGradient |
generated | CSS colour or { from, to, angle? } gradient. |
skin |
string |
generated | Any CSS colour. |
hair |
"short" | "thick" | "mohawk" | "long" | "bob" | "buzz" | "none" |
generated | Only drawn when hat is "none", so hats keep their silhouette. |
hairColor |
string |
generated | Any CSS colour. |
highlight |
boolean |
false |
Adds the lighter second tone to the mohawk artwork. Shirts always keep their built-in fold shading. |
hat |
"none" | "beanie" | "turban" |
generated | Usually "none". A hat replaces the hair silhouette; hair stays in the config. |
hatColor |
string |
generated | Any CSS colour. Generated values come from the palette's hats list; an explicit value always wins. |
ears |
"small" | "big" |
generated | |
eyes |
"round" | "oval" | "smile" |
generated | |
brows |
"straight" | "arched" |
generated | Independent of hair. |
glasses |
"none" | "round" | "square" |
generated | Usually "none". |
nose |
"short" | "round" | "long" |
generated | |
mouth |
"smile" | "laugh" | "peace" |
generated | |
shirt |
"tee" | "hoodie" | "polo" |
generated | |
shirtColor |
string |
generated | Any CSS colour. |
shape |
"circle" | "rounded" | "square" | "none" |
"circle" |
Stored in the config so <Avatar {...config} /> round-trips. |
facialHair |
"none" | "moustache" | "handlebar" | "beard" | "goatee" | "stubble" |
"none" |
Opt-in 1.1 part; handlebar draws a walrus silhouette. Not generated for new seeds so seeded output stays stable. |
earring |
"none" | "stud" | "hoop" |
"none" |
Opt-in 1.1 accessory on the earlobe. |
headphones |
"none" | "over-ear" |
"none" |
Opt-in 1.1 accessory drawn above hair and hats. |
headphoneColor |
string |
"#506AF4" |
Only used when headphones is set. |
AvatarColor is a string holding any CSS colour (#rgb, #rrggbb, rgb(),
oklch(), a named colour, …). Invalid values fall back to the palette colour.
- The same
seedand options produce a deeply equal config on every call, on every platform, and across versions of react-avatar-kit. - Adding an override never changes the untouched fields: each field is drawn from its own seeded stream.
- Seeds are stable data, not art direction. A future major version may change the artwork behind a seed; it will not silently change a version-1 seed.
- No seed means the fixed seed
"default", not randomness, so server and client HTML always match.
const palettes: Record<PaletteName, Palette>
interface Palette {
name: PaletteName
skins: string[]
hair: string[]
hats: string[]
shirts: string[]
backgrounds: string[]
gradients: AvatarGradient[]
accents: string[]
}Read-only catalogue of the colours used for generated avatars. Useful for building
editors and theme pickers. createAvatar({ palette: "pastel", seed: "ada" }) uses it;
individual colours can be overridden afterwards.
interface AvatarToSvgOptions {
size?: number
alt?: string
title?: string
shape?: Shape
}
// import { avatarToSvg } from 'react-avatar-kit/server'
function avatarToSvg(
input?: string | AvatarConfig | AvatarOptions,
options?: AvatarToSvgOptions
): stringRenders a standalone SVG document as a string, for Open Graph images, email templates,
static site generation or a canvas/PNG pipeline. It lives on the server subpath so the
browser entry never pulls in react-dom/server.
import { avatarToSvg } from 'react-avatar-kit/server'
const markup = avatarToSvg('ada@example.com', { size: 512, alt: 'Ada' })| Specifier | Contents |
|---|---|
react-avatar-kit |
Avatar, createAvatar, palettes, all public types |
react-avatar-kit/core |
createAvatar, palettes, all public types — no React import |
react-avatar-kit/server |
avatarToSvg for non-browser rendering |
src/index.ts is the entire public surface of the component entry point:
export { Avatar } from './react/avatar'
export { createAvatar } from './core/create-avatar'
export { palettes } from './core/palettes'
export type { AvatarProps } from './react/avatar'
export type {
AvatarColor,
AvatarConfig,
AvatarGradient,
AvatarOptions,
BrowStyle,
EarSize,
Earring,
EyeStyle,
FacialHair,
Headphones,
GlassesStyle,
HairStyle,
HatStyle,
MouthStyle,
NoseStyle,
Palette,
PaletteName,
Shape,
ShirtStyle,
} from './core/types'avatarToSvg is the fourth public runtime function and lives on the
react-avatar-kit/server subpath.
Type signatures:
type Shape = 'circle' | 'rounded' | 'square' | 'none'
type HairStyle = 'short' | 'thick' | 'mohawk' | 'long' | 'bob' | 'buzz' | 'none'
type HatStyle = 'none' | 'beanie' | 'turban'
type EyeStyle = 'round' | 'oval' | 'smile'
type BrowStyle = 'straight' | 'arched'
type GlassesStyle = 'none' | 'round' | 'square'
type NoseStyle = 'short' | 'round' | 'long'
type MouthStyle = 'smile' | 'laugh' | 'peace'
type ShirtStyle = 'tee' | 'hoodie' | 'polo'
type PaletteName = 'default' | 'pastel' | 'vivid' | 'mono' | 'earth' | 'neon'
type EarSize = 'small' | 'big'
type FacialHair = 'none' | 'moustache' | 'handlebar' | 'beard' | 'goatee' | 'stubble'
type Earring = 'none' | 'stud' | 'hoop'
type Headphones = 'none' | 'over-ear'
type AvatarColor = string
interface AvatarGradient { from: string; to: string; angle?: number }
interface AvatarConfig extends Required<Omit<AvatarOptions, 'background'>> {
background: AvatarColor | AvatarGradient
}The component ships no CSS. className, style and size cover layout, and every
colour is a plain CSS colour, so a design system can theme avatars directly:
<Avatar seed={user.id} size="2.5rem" shape="rounded" className="ring-2 ring-white" /><Avatar /> renders deterministically from props alone. It needs no "use client"
boundary, no effects and no layout measurement, so it can be rendered inside a React
Server Component, streamed with renderToPipeableStream, or pre-rendered to HTML.
// app/page.tsx — a React Server Component, no "use client"
import { Avatar } from 'react-avatar-kit'
export default function Page() {
return <Avatar seed="ada@example.com" size={80} alt="Ada" />
}The old <Avatar {...genConfig(seed)} /> pattern becomes one line:
- import Avatar, { genConfig } from 'react-nice-avatar'
- <Avatar {...genConfig('hi@example.com')} style={{ width: 64, height: 64 }} />
+ import { Avatar } from 'react-avatar-kit'
+ <Avatar seed="hi@example.com" size={64} />| Old | New |
|---|---|
genConfig(seed) |
createAvatar(seed) |
genConfig({ ... }) |
createAvatar({ seed, ... }) |
shape prop |
shape prop (none added) |
sex |
removed; hair, brows and everything else are independent |
hairStyle: "normal" |
hair: "short" |
hairStyle: "womanLong" |
hair: "long" |
hairStyle: "womanShort" |
hair: "bob" |
eyeStyle: "circle" |
eyes: "round" |
eyeBrowStyle |
brows: "straight" | "arched" |
glassesStyle |
glasses |
noseStyle |
nose |
mouthStyle |
mouth |
hatStyle |
hat |
shirtStyle: "short" | "hoody" |
shirt: "tee" | "hoodie" |
bgColor + isGradient |
background: string | { from, to, angle? } |
hairColorRandom |
highlight |
faceColor |
skin |
earSize |
ears |
Seeded output is intentionally not compatible with the old library: the generator was
rebuilt (independent per-field streams, contrast-aware colour picking). Pass an explicit
config if you need to preserve stored avatars exactly.
1.xkeeps the export names, option names, and the determinism contract.- The
exportsmap is part of the contract:react-avatar-kit,/coreand/serverstay resolvable from both ESM and CommonJS. - Dropping a React major is a major version.