React component for Avataaars

The core React component for Avataaars Generator developed by Fang-Pen Lin, based on the Sketch library Avataaars designed by Pablo Stanley.

Quick Links

• 🎨 Live Demo - Interactive playground to test all features
• 📚 API Documentation - Complete TypeDoc API reference
• 📦 npm Package - Install via npm
• 💻 Demo Source Code - Learn how to build your own editor

Features

• React 19 compatible - Full support for React 18 and 19
• Animation features - Optional hover animations and expression sequences
• Automatic responsive sizing - Avatars automatically scale to fit viewport on smaller screens
• Export support - Export avatars as static SVG, animated SVG, or GIF
• SVG based
• Light weight
• Scalable
• Easy to use
• Easy to integrate with custom editor
• Comes with editor

Installation

npm install @vierweb/avataaars
Copy

Usage

Basic Avatar

import Avatar from "@vierweb/avataaars";

function MyAvatar() {
  return (
    <Avatar
      style={{ width: "300px", height: "300px" }}
      avatarStyle="Circle"
      topType="LongHairMiaWallace"
      accessoriesType="Prescription02"
      hairColor="BrownDark"
      facialHairType="Blank"
      clotheType="Hoodie"
      clotheColor="PastelBlue"
      eyeType="Happy"
      eyebrowType="Default"
      mouthType="Smile"
      skinColor="Light"
    />
  );
}
Copy

With Animation Features

import Avatar from "@vierweb/avataaars";

function AnimatedAvatar() {
  return (
    <Avatar
      avatarStyle="Circle"
      topType="LongHairStraight"
      eyeType="Happy"
      mouthType="Smile"
      skinColor="Light"
      // Idle animation: random expression changes every 2 seconds
      animationSpeed={2000}
      // Hover scale: avatar scales up on hover
      hoverScale={1.2}
      // Hover animation: cycle through expressions on hover
      hoverSequence={[
        { mouthType: "Disbelief", eyeType: "Surprised", eyebrowType: "UpDown" },
        { mouthType: "ScreamOpen", eyeType: "Dizzy", eyebrowType: "Angry" },
        { mouthType: "Smile", eyeType: "Happy", eyebrowType: "Default" },
      ]}
      hoverAnimationSpeed={300}
      backgroundColor="#65C9FF"
    />
  );
}
Copy

Individual Avatar Pieces

To showcase individual pieces of the avatar, use the Piece component:

import { Piece } from "@vierweb/avataaars";

function AvatarPieces() {
  return (
    <>
      <Piece pieceType="mouth" pieceSize="100" mouthType="Eating" />
      <Piece pieceType="eyes" pieceSize="100" eyeType="Dizzy" />
      <Piece pieceType="eyebrows" pieceSize="100" eyebrowType="RaisedExcited" />
      <Piece pieceType="accessories" pieceSize="100" accessoriesType="Round" />
      <Piece
        pieceType="top"
        pieceSize="100"
        topType="LongHairFro"
        hairColor="Red"
      />
      <Piece
        pieceType="facialHair"
        pieceSize="100"
        facialHairType="BeardMajestic"
      />
      <Piece
        pieceType="clothe"
        pieceSize="100"
        clotheType="Hoodie"
        clotheColor="Red"
      />
      <Piece pieceType="graphics" pieceSize="100" graphicType="Skull" />
      <Piece pieceType="skin" pieceSize="100" skinColor="Brown" />
    </>
  );
}
Copy

TypeScript Support

The package includes full TypeScript support with exported types for type safety:

import Avatar, {
  type Props,
  type HoverExpression,
  AvatarStyle,
} from "@vierweb/avataaars";

// Type your component props
interface MyComponentProps {
  avatarProps: Props;
}

function MyAvatar({ avatarProps }: MyComponentProps) {
  // Type-safe hover sequence
  const hoverSequence: HoverExpression[] = [
    { mouthType: "Disbelief", eyeType: "Surprised", eyebrowType: "UpDown" },
    { mouthType: "Smile", eyeType: "Happy", eyebrowType: "Default" },
  ];

  return (
    <Avatar
      {...avatarProps}
      avatarStyle={AvatarStyle.Circle}
      hoverSequence={hoverSequence}
    />
  );
}
Copy

Available Types:

• Props (alias for AvatarProps) - Component props interface
• HoverExpression - Type for hover animation sequences
• AvatarStyle - Enum for avatar styles (Circle, Transparent)
• OptionKey - Type for avatar option keys

Animation Props

The Avatar component supports several optional animation features that can be used independently or combined:

• animationSpeed (number, 500-3000ms): Controls random expression changes when not hovering. Lower values = faster changes.
• hoverScale (number, 1.05-1.32): Scales the avatar on hover. Visual effect only.
• hoverSequence (HoverExpression[]): Array of expressions to cycle through on hover.
• hoverAnimationSpeed (number, 100-2000ms): Speed of hover sequence animation.
• backgroundColor (string): Background color for circle style avatars (hex color).
• maskBackgroundColor (string): Explicit color for the clip mask overlay. When provided, bypasses auto-detection for instant updates. Ideal for dynamic themes where the parent background changes frequently.

interface HoverExpression {
  mouthType: string;
  eyeType: string;
  eyebrowType: string;
}
Copy

With Dynamic Theme Background

For applications with dynamic themes (e.g., theme sliders), use maskBackgroundColor for instant synchronization:

import Avatar from "@vierweb/avataaars";

function ThemedAvatar({ themeColor }) {
  return (
    <Avatar
      avatarStyle="Circle"
      topType="LongHairStraight"
      eyeType="Happy"
      mouthType="Smile"
      skinColor="Light"
      backgroundColor="#65C9FF"
      // Pass theme color directly for instant updates (bypasses auto-detection)
      maskBackgroundColor={themeColor}
      hoverScale={1.2}
    />
  );
}
Copy

To explore all avatar options and generate React code, check out our interactive demo.

Development

# Install dependencies
npm install

# Start development (builds package, generates docs, and starts demo server)
npm start

# Build the package
npm run build

# Run linter
npm run lint

# Generate documentation
npm run docs

# Run demo only (builds package and starts dev server)
npm run demo
Copy

For more information on running the interactive demo locally, see the demo README.

Building Your Own Editor

To build a custom avatar editor, you can use the Avatar component along with OptionContext to collect and manage available options. For complete examples, see:

• Our demo source code - Full-featured editor implementation
• API Documentation - Complete TypeDoc reference with all types and interfaces