React Usage

@avatar-generator/react wraps createAvatar in a component that renders an <img> whose src is the generated SVG as a data URI. It works with React 18 and 19.

Basic usage

import { Avatar } from "@avatar-generator/react";
import { initials } from "@avatar-generator/style-initials";

function UserProfile({ user }) {
    return <Avatar style={initials} options={{ seed: user.id, name: user.name, size: 48 }} alt={user.name} />;
}

Using different styles

The style prop takes the style object itself, so a gallery is just a list of imports:

import { Avatar } from "@avatar-generator/react";
import { initials } from "@avatar-generator/style-initials";
import { geometric } from "@avatar-generator/style-geometric";
import { pixels } from "@avatar-generator/style-pixels";
import { rings } from "@avatar-generator/style-rings";
import { faces } from "@avatar-generator/style-faces";
import { illustrated } from "@avatar-generator/style-illustrated";
import { anime } from "@avatar-generator/style-anime";
import { abstract } from "@avatar-generator/style-abstract";
import { emoji } from "@avatar-generator/style-emoji";
import { animals } from "@avatar-generator/style-animals";
import { gradient } from "@avatar-generator/style-gradient";

const STYLES = [
    { style: initials, label: "Initials" },
    { style: geometric, label: "Geometric" },
    { style: pixels, label: "Pixels" },
    { style: rings, label: "Rings" },
    { style: faces, label: "Faces" },
    { style: illustrated, label: "Illustrated" },
    { style: anime, label: "Anime" },
    { style: abstract, label: "Abstract" },
    { style: emoji, label: "Emoji" },
    { style: animals, label: "Animals" },
    { style: gradient, label: "Gradient" },
];

function AvatarGallery({ userId }) {
    const options = { seed: userId, size: 64 };

    return (
        <div className="avatar-gallery">
            {STYLES.map(({ style, label }) => (
                <Avatar key={label} style={style} options={options} alt={label} />
            ))}
        </div>
    );
}

With custom options

import { Avatar } from "@avatar-generator/react";
import { geometric } from "@avatar-generator/style-geometric";

function CustomAvatar({ userId }) {
    return (
        <Avatar
            style={geometric}
            options={{
                seed: userId,
                size: 96,
                square: true,
                colors: ["#FF6B6B", "#4ECDC4", "#45B7D1"],
                border: { width: 2, color: "#333" },
            }}
            className="custom-avatar"
            alt="User avatar"
        />
    );
}

TypeScript

Import the option type from the style package — in v3 the style owns its own types, not core:

import { Avatar } from "@avatar-generator/react";
import { initials, type InitialsOptions } from "@avatar-generator/style-initials";

interface UserAvatarProps {
    userId: string;
    userName: string;
}

function UserAvatar({ userId, userName }: UserAvatarProps) {
    const options: InitialsOptions = {
        seed: userId,
        name: userName,
        size: 48,
        fontWeight: 700,
    };

    return <Avatar style={initials} options={options} alt={userName} />;
}

Option types moved in v3

InitialsOptions and its siblings used to come from @avatar-generator/core. They now come from the style package. See the Migration Guide.

AvatarProps<T> is exported too, if you need to wrap the component:

import type { AvatarProps } from "@avatar-generator/react";

Props

Prop	Type	Default	Description
style	Style<T>	(required)	The style object to render with
options	T extends AvatarOptions	(required)	Seed and style-specific options
alt	string	"Avatar"	Alt text for the rendered <img>
className	string	—	Class applied to the <img>

The rendered element is an <img> sized from options.size (default 64), so give it a meaningful alt — or alt="" if the avatar is decorative and the name is already shown as text next to it.

Memoization

The component memoizes generation with useMemo(…, [style, options]). Because that compares by identity, an inline object literal creates a new options on every render and defeats the memo:

// Regenerates on every parent render — the object is new each time
<Avatar style={initials} options={{ seed: user.id, size: 48 }} alt={user.name} />

Usually that is fine: generating an avatar is a little string building, not a network call. For a long list, give each row a stable options object by memoizing inside the row component — never inside a .map() callback, which would break the rules of hooks:

import { Avatar } from "@avatar-generator/react";
import { initials } from "@avatar-generator/style-initials";
import { useMemo } from "react";

function UserRow({ user }) {
    const options = useMemo(() => ({ seed: user.id, name: user.name, size: 32 }), [user.id, user.name]);

    return (
        <li>
            <Avatar style={initials} options={options} alt="" />
            <span>{user.name}</span>
        </li>
    );
}

function UserList({ users }) {
    return (
        <ul>
            {users.map((user) => (
                <UserRow key={user.id} user={user} />
            ))}
        </ul>
    );
}

If you would rather cache across components entirely, see the caching recipe in the Cookbook.

Server-side rendering

The component is safe in a React Server Component or during renderToString: createAvatar touches no browser globals, and the output is an <img> with a data URI, so there is nothing to hydrate. If you would rather inline the SVG markup than embed a data URI, call createAvatar directly — see the SSR recipe in the Cookbook.