PixelAvatar

Displays a user identity as an initials-or-image badge with optional status dot, tone, shape, and deterministic colored fallback.

  • Initials fallback locale-aware via PxlKitLocale (uppercases per locale rules)
  • Five sizes (xs/sm/md/lg/xl) and three shapes (circle/rounded/square)
  • Optional status dot (online/away/busy/offline) baked into the accessible name
  • Deterministic tinted fallback via colorSeed (djb2 hash → tone palette)
  • Lazy/async image loading when src is provided
Status
stable
Category
data
Since
v1.0.0

API

import { PixelAvatar } from '@pxlkit/ui-kit';
PropTypeDefaultDescription
name (required)string—Display name. Used to derive initials and the accessible label.
srcstring—Optional image source. Falls back to initials on load failure.
size'xs' | 'sm' | 'md' | 'lg' | 'xl''md'Size token. Defaults to 'md'.
tone'green' | 'cyan' | 'gold' | 'red' | 'purple' | 'pink' | 'neutral'—Tone tint for the initials fallback. Overrides colorSeed.
surface'pixel' | 'linear'—Visual surface override.
status'online' | 'away' | 'busy' | 'offline'—Status dot rendered in the bottom-right corner.
shape'square' | 'circle' | 'rounded'—Shape of the avatar frame. Defaults to 'circle'.
colorSeedstring—Deterministic tone fallback derived from the seed via hash modulo a fixed tone palette. Overridden by an explicit tone prop.

ref points to <div>.

Accessibility

WCAG target: 2.1 AA

  • img

Avatar is a presentational identity badge. The user name is exposed via title; when status is set the frame becomes role="img" named by the user name plus the status word (no live region — status dots are not transient announcements). When src is provided the inner <img> uses the same accessible name as its alt text.

Usage

import { PixelAvatar } from '@pxlkit/ui-kit';

export function Default() {
  return <PixelAvatar name="Joangel De La Rosa" />;
}

Examples

Default

import { PixelAvatar } from '@pxlkit/ui-kit';

export function Default() {
  return <PixelAvatar name="Joangel De La Rosa" />;
}

Sizes

import { PixelAvatar } from '@pxlkit/ui-kit';

export function Sizes() {
  return (
    <div className="flex items-end gap-3">
      <PixelAvatar name="Ana Lopez" size="xs" />
      <PixelAvatar name="Ana Lopez" size="sm" />
      <PixelAvatar name="Ana Lopez" size="md" />
      <PixelAvatar name="Ana Lopez" size="lg" />
      <PixelAvatar name="Ana Lopez" size="xl" />
    </div>
  );
}

Tones

import { PixelAvatar } from '@pxlkit/ui-kit';

export function Tones() {
  return (
    <div className="flex flex-wrap gap-3">
      <PixelAvatar name="Green User" tone="green" />
      <PixelAvatar name="Cyan User" tone="cyan" />
      <PixelAvatar name="Gold User" tone="gold" />
      <PixelAvatar name="Red User" tone="red" />
      <PixelAvatar name="Purple User" tone="purple" />
      <PixelAvatar name="Pink User" tone="pink" />
      <PixelAvatar name="Neutral User" tone="neutral" />
    </div>
  );
}

Surfaces

import { PixelAvatar } from '@pxlkit/ui-kit';

export function Surfaces() {
  return (
    <div className="flex items-center gap-3">
      <PixelAvatar name="Pixel Surface" surface="pixel" />
      <PixelAvatar name="Linear Surface" surface="linear" />
    </div>
  );
}

Shapes

import { PixelAvatar } from '@pxlkit/ui-kit';

export function Shapes() {
  return (
    <div className="flex items-center gap-3">
      <PixelAvatar name="Circle Shape" shape="circle" />
      <PixelAvatar name="Rounded Shape" shape="rounded" />
      <PixelAvatar name="Square Shape" shape="square" />
    </div>
  );
}

Statuses

import { PixelAvatar } from '@pxlkit/ui-kit';

export function Statuses() {
  return (
    <div className="flex items-center gap-3">
      <PixelAvatar name="Online User" status="online" />
      <PixelAvatar name="Away User" status="away" />
      <PixelAvatar name="Busy User" status="busy" />
      <PixelAvatar name="Offline User" status="offline" />
    </div>
  );
}

With Image

import { PixelAvatar } from '@pxlkit/ui-kit';

export function WithImage() {
  return (
    <PixelAvatar
      name="Joangel"
      src="https://i.pravatar.cc/80?img=12"
      size="lg"
      status="online"
    />
  );
}

Color Seed

import { PixelAvatar } from '@pxlkit/ui-kit';

export function ColorSeed() {
  return (
    <div className="flex items-center gap-3">
      <PixelAvatar name="Alice Adams" colorSeed="alice@example.com" />
      <PixelAvatar name="Bob Brown" colorSeed="bob@example.com" />
      <PixelAvatar name="Carol Chen" colorSeed="carol@example.com" />
      <PixelAvatar name="Dave Diaz" colorSeed="dave@example.com" />
    </div>
  );
}

Related