Avatar

A picture of a person or a thing, at a known size. It draws the picture when there is one and stands in for it with initials, a glyph or a silhouette when there is not, so it is never an empty box.

import { Avatar } from 'neba';

<Avatar src="/people/jane.jpg" name="Jane Doe" />
<Avatar name="Jane Doe" />
<Avatar shape="square" variant="solid" color="info">N</Avatar>;

Props

Prop	Type	Default	Description
src	string	—	The picture. Until it loads(and forever, if it fails) the fallback is what is drawn
srcSet	string	—	Candidate images at other resolutions, as on any img
alt	string	name	The picture's alt text. Falls back to name, and to an empty string when there is neither
name	string	—	Who or what this is. It names the picture, the initials are derived from it, and a screen reader hears it instead of them
initials	string	—	The initials, written out, for when the first-and-last-word rule derives the wrong ones
shape	'circle' | 'square'	'circle'	The crop. square cuts the corners off instead, at roughly 28% of the box
variantshared	'solid' | 'outline' | 'text'	'text'	Weight of the surface behind the fallback. Invisible once a picture has loaded, apart from the edge it keeps
sizeshared	'xs' | 'sm' | 'md' | 'lg' | 'xl'	'md'	The box the picture is drawn in: the control heights, so an avatar and the button beside it are the same height
colorshared	'primary' | 'secondary' | 'success' | 'warning' | 'danger' | 'info'	'primary'	Semantic colour role. Arbitrary colour values are not accepted
elevationshared	0 | 1 | 2 | 3	0	Drop shadow depth. 0 means no shadow at all
delay	number	—	How long to wait before drawing the fallback, in milliseconds. Stops the initials flashing up in front of a cached picture
imageProps	Omit<ComponentPropsWithoutRef<'img'>, 'src' | 'srcSet' | 'alt'>	—	Anything else the img needs: loading, crossOrigin, referrerPolicy
onLoadingStatusChange	(status: 'idle' | 'loading' | 'loaded' | 'error') => void	—	Called as the picture moves between its four loading states
children	ReactNode	—	The fallback, drawn instead of the initials. An icon, a logo, a single emoji
transitionshared	NebaTransition	—	An entrance animation, run once on mount (transition="fade"). Wrap it in an Animate* component for a trigger or a replay

Every other <span> attribute passes through to the root. The <img> takes src, srcSet and alt directly; anything else it needs goes in imageProps.

The shared axes (variant size color elevation) are defined in prop conventions. density is not offered: an avatar has no padding to change.

Examples

variant and color

solid is a filled circle, outline a hairline over a faint panel, text (the default) a tinted plate with no edge. color picks one of the six role colours. All three are invisible behind a loaded picture, apart from the edge they keep.

import { Avatar } from 'neba';

const COLORS = ['primary', 'secondary', 'success', 'warning', 'danger', 'info'] as const;

export default function AvatarVariants() {
  return (
    <div className="flex flex-col gap-4">
      {(['solid', 'outline', 'text'] as const).map((variant) => (
        <div key={variant} className="flex flex-wrap items-center gap-3">
          {COLORS.map((color) => (
            <Avatar key={color} variant={variant} color={color} name="Jane Doe" size="lg" />
          ))}
        </div>
      ))}
    </div>
  );
}

size

The control height ladder, so an avatar and the Button beside it in a row are the same height: 22, 26, 32, 40 and 48px. The initials are sized off the box rather than off the row, at roughly 40% of the diameter.

import { Avatar, Button } from 'neba';

const SIZES = ['xs', 'sm', 'md', 'lg', 'xl'] as const;

export default function AvatarSizes() {
  return (
    <div className="flex flex-col gap-5">
      <div className="flex flex-wrap items-end gap-3">
        {SIZES.map((size) => (
          <Avatar key={size} size={size} src="/samples/people/anya-sol.jpg" name="Anya Sol" />
        ))}
      </div>
      <div className="flex flex-wrap items-end gap-3">
        {SIZES.map((size) => (
          <Avatar key={size} size={size} name="Anya Sol" color="info" />
        ))}
      </div>
      {/* An avatar is on the control ladder, so it lines up with the button beside it. */}
      <div className="flex flex-wrap items-center gap-3">
        {SIZES.map((size) => (
          <div key={size} className="flex items-center gap-2">
            <Avatar size={size} name="Anya Sol" />
            <Button size={size} variant="outline" color="secondary">
              {size}
            </Button>
          </div>
        ))}
      </div>
    </div>
  );
}

shape

circle is the default crop. square cuts the corners off instead, at roughly 28% of the box: use it for a logo or a repository icon, which are drawn to the edges of a rectangle and lose those edges to a round crop.

import { Avatar } from 'neba';

const SIZES = ['sm', 'md', 'lg', 'xl'] as const;

export default function AvatarShape() {
  return (
    <div className="flex flex-col gap-5">
      <div className="flex flex-wrap items-end gap-3">
        {SIZES.map((size) => (
          <Avatar
            key={size}
            size={size}
            shape="circle"
            src="/samples/people/theo-quinn.jpg"
            name="Theo Quinn"
          />
        ))}
      </div>
      <div className="flex flex-wrap items-end gap-3">
        {SIZES.map((size) => (
          <Avatar
            key={size}
            size={size}
            shape="square"
            src="/samples/people/theo-quinn.jpg"
            name="Theo Quinn"
          />
        ))}
      </div>
      <div className="flex flex-wrap items-end gap-3">
        {SIZES.map((size) => (
          <Avatar
            key={size}
            size={size}
            shape="square"
            variant="solid"
            color="secondary"
            name="Neba UI"
          />
        ))}
      </div>
    </div>
  );
}

name and initials

name does three things: it becomes the picture's alt, the initials are derived from it, and a screen reader hears it instead of them.

The rule is the first character of the first word plus the first character of the last: Jane Doe is JD, jane miriam van doe is JD, 홍길동 is 홍. Decomposed accents are recomposed first, so Ängela is Ä and not A. When the rule picks the wrong letters, write them out in initials.

import { Avatar } from 'neba';

const PEOPLE = [
  { name: 'Jane Doe' },
  { name: 'jane miriam van doe' },
  { name: '홍길동' },
  { name: 'Ada' },
  { name: 'Jane Doe', initials: 'vD' }
];

export default function AvatarInitials() {
  return (
    <div className="flex flex-wrap items-center gap-6">
      {PEOPLE.map((person) => (
        <div key={person.initials ?? person.name} className="flex flex-col items-center gap-2">
          <Avatar size="xl" color="info" name={person.name} initials={person.initials} />
          <code className="text-[0.75rem] text-(--neba-muted-fg)">
            {person.initials ? `initials="${person.initials}"` : `"${person.name}"`}
          </code>
        </div>
      ))}
    </div>
  );
}

children

children is the fallback, drawn instead of the initials: an icon, a logo, a single emoji. An <svg> inside it is sized to 55% of the box. With no children, no initials and no name, the avatar draws a silhouette.

Which of the three is showing is decided by the picture's loading state. Set delay to hold the fallback back for a moment so the initials do not flash up in front of a cached image, and read the state itself with onLoadingStatusChange.

import { Avatar } from 'neba';

function RobotIcon() {
  return (
    <svg viewBox="0 0 24 24" fill="none" aria-hidden="true">
      <rect
        x="3.5"
        y="7.5"
        width="17"
        height="13"
        rx="3.5"
        stroke="currentColor"
        strokeWidth="1.6"
      />
      <path d="M12 3.5v4" stroke="currentColor" strokeWidth="1.6" strokeLinecap="round" />
      <circle cx="9" cy="13.5" r="1.5" fill="currentColor" />
      <circle cx="15" cy="13.5" r="1.5" fill="currentColor" />
    </svg>
  );
}

export default function AvatarFallback() {
  return (
    <div className="flex flex-wrap items-center gap-6">
      {/* Loads, so nothing else is ever drawn. */}
      <Avatar size="xl" src="/samples/people/noa-marin.jpg" name="Noa Marin" />

      {/* Fails, so the initials take over. */}
      <Avatar size="xl" src="/not-a-real-image.png" name="Jane Doe" color="danger" />

      {/* No picture at all: children stand in for it. */}
      <Avatar size="xl" name="Deploy bot" color="secondary">
        <RobotIcon />
      </Avatar>

      <Avatar size="xl" variant="solid" color="warning">
        🐈
      </Avatar>

      {/* Nothing to go on at all. */}
      <Avatar size="xl" color="secondary" />
    </div>
  );
}

Status marks

An avatar carries no status dot of its own. Wrap it in a Badge with overlap="circle", which tucks the marker in by the amount a circle's corner sits inside its bounding box.

import { Avatar, Badge } from 'neba';

export default function AvatarStatus() {
  return (
    <div className="flex flex-wrap items-center gap-6">
      <Badge dot color="success" overlap="circle" label="Online">
        <Avatar size="xl" src="/samples/people/lucas-adebayo.jpg" name="Lucas Adebayo" />
      </Badge>

      <Badge dot color="warning" overlap="circle" label="Away">
        <Avatar size="xl" name="Sam Park" color="warning" />
      </Badge>

      <Badge dot color="secondary" overlap="circle" placement="bottom-end" label="Offline">
        <Avatar size="xl" src="/samples/people/helen-voss.jpg" name="Helen Voss" />
      </Badge>

      <Badge content={12} overlap="circle" label="12 unread messages">
        <Avatar size="xl" name="홍길동" color="info" />
      </Badge>
    </div>
  );
}

Accessibility

• JD read out loud is two letters, not a person. Given a name, the initials are hidden from the accessibility tree and the name becomes the fallback's accessible name instead.
• With neither name nor alt the <img> gets an empty alt, so it is skipped rather than read out as a file name. That is the right default for an avatar sitting next to the person's own name; pass alt when the picture is the only thing identifying them.
• A children glyph with no name says nothing. Give the avatar a name (or an aria-label on whatever wraps it) when the glyph is carrying the meaning on its own.