Skip to content

PersonAvatar

Use PersonAvatar to show a person with the pixel portrait they made in Raft’s avatar builder, so they look the same here as in Raft. For an agent, use PixelAvatar; for an uploaded picture or initials, use Avatar.

Before you start

Import it from its own entry point; it is not exported from @pika-lab/react:

tsx
import { PersonAvatar } from "@pika-lab/react/person-avatar";

PersonAvatar draws a person’s pixel portrait, the one Raft’s avatar builder makes: a 112×112 picture composed from a recipe of seven choices (background, skin, hair, hair color, expression, headwear and glasses). It draws exactly what Raft draws for the same recipe.

It has the same frame as PixelAvatar: size, round, bordered, alt, and it stacks in an AvatarGroup. The art is about 230 KB (under 6 KB gzipped), so it has its own entry, and apps that don’t show people’s avatars never load it.

Demos

Basic

A field left out of recipe takes Raft’s default: yellow, a cap, short black hair, a wink.

Builder

personAvatarOptions lists every field’s choices in the builder’s order, and randomPersonAvatarRecipe shuffles them as Raft does. toRaftPersonAvatar gives the value Raft stores.

Raft avatars

readRaftPersonAvatar reads a person’s Raft avatarUrl (pixel-human:v1:…) as Raft does: an unknown field draws its default, and it returns null for anything else, which PixelAvatar can draw.

Props

NameTypeDefaultDescriptionVersion
recipePartial<PersonAvatarRecipe>{}The look. A missing or unknown field draws Raft’s default for it.Unreleased
sizesmall | medium | large | numbermediumNamed control height, or a side length in px.Unreleased
roundbooleanfalseA circle instead of the theme’s shape.Unreleased
borderedbooleantrueThe theme’s frame around the art.Unreleased
altstringundefinedThe accessible name. Without it the avatar is decorative (aria-hidden).Unreleased

Other props go to the root <span>. size, round and bordered can be set for every PersonAvatar with ConfigProvider’s componentOptions.PersonAvatar.

Helpers

NameDescription
personAvatarOptionsEach field’s option ids, in the builder’s order.
defaultPersonAvatarRecipeRaft’s default look.
randomPersonAvatarRecipe(random?)A random look: half wear something on the head, about a third glasses.
readRaftPersonAvatar(value)The recipe in a Raft pixel-human: value, or null.
toRaftPersonAvatar(recipe)The recipe as Raft stores it.

The art is copied from Raft by pnpm --filter @pika-lab/scripts sync:raft-avatars <Raft checkout>; personAvatarArtVersion is its version.