PlAvatar

A picture of a person or a thing, at a known size, that is never an empty box. When there is no picture there are initials; when there are no initials there is a silhouette.

React

import { PlAvatar } from 'plass-ui';

<PlAvatar name="Nadia Rowan" src="/nadia-rowan.webp" />;
<PlAvatar name="Nadia Rowan" />;

import 'package:plass_ui/plass_ui.dart';

const PlAvatar(name: 'Nadia Rowan', image: NetworkImage('/nadia-rowan.webp'));
const PlAvatar(name: 'Nadia Rowan');

Props

Prop	Type	Default	Description
variantshared	'solid' | 'glass' | 'ghost'	'ghost'	What the sheet behind the fallback is made of — invisible once a picture has loaded, apart from the edge it keeps. ghost by default, because a page of saturated circles is a page nobody can read a name off
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 in a toolbar are the same height
colorshared	'primary' | 'secondary' | 'success' | 'warning' | 'danger' | 'info'	'primary'	Semantic colour role. An avatar is the thing being coloured, so its sheet takes the tint
elevationshared	0 | 1 | 2 | 3	0	Drop shadow depth. An avatar is a picture set into the page rather than a key resting on it
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	—	What the picture says. Defaults to name, and to an empty string when there is no name
name	string	—	Who or what this is. It names the picture, the initials are derived from it, and it is what a screen reader hears instead of them
initials	string	—	The initials, written out, for when the derivation rule got them wrong
shape	'circle' | 'square'	'circle'	The crop. circle for a portrait, square for the library’s own fillet — for a logo or an icon drawn to the edges of a rectangle
delay	number	—	How long to wait before drawing the fallback, in milliseconds. Set it to about the time a cached image takes and the initials stop flashing
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 the four loading states
children	ReactNode	—	The fallback, drawn instead of the initials — an icon, a logo, a single emoji

Prop	Type	Default	Description
variantshared	PlassVariant?	PlassVariant.ghost	What the sheet behind the fallback is made of — invisible once a picture has loaded, apart from the edge it keeps. ghost by default, because a page of saturated circles is a page nobody can read a name off
sizeshared	PlassSize?	PlassSize.md	The box the picture is drawn in — the control heights, so an avatar and the button beside it in a toolbar are the same height
colorshared	PlassColor?	PlassColor.primary	Semantic colour role. An avatar is the thing being coloured, so its sheet takes the tint
elevationshared	int?	0	Drop shadow depth. An avatar is a picture set into the page rather than a key resting on it
image	ImageProvider?	—	The picture, as an ImageProvider rather than a URL — a NetworkImage, an AssetImage or a provider from a caching package all fit. Until it loads, and forever if it fails, the fallback is what is drawn
name	String?	—	Who or what this is. It names the picture, the initials are derived from it, and it is what a screen reader hears instead of them
initials	String?	—	The initials, written out, for when the derivation rule got them wrong
semanticLabel	String?	—	What the picture says. Defaults to name, and to an empty string when there is no name
shape	PlAvatarShape?	PlAvatarShape.circle	The crop. circle for a portrait, square for the library’s own fillet — for a logo or an icon drawn to the edges of a rectangle
child	Widget?	—	The fallback, drawn instead of the initials — an icon, a logo, a single emoji

Every native <span> attribute passes straight through. color is excluded from the pass-through because it is a Plass prop here.

image is an ImageProvider rather than a URL, which is the shape every image in Flutter has: a NetworkImage, an AssetImage, a MemoryImage or a provider from a caching package all fit without the component having to know which.

There is no density: an avatar has no padding to tighten. It carries no status dot of its own either. An avatar with a green mark on it is a PlBadge with an avatar in it.

What the shared axes (variant size color elevation) mean across the library is in prop conventions.

Examples

The fallback

Three things can be drawn and exactly one of them is at a time: the picture, if src is given and it loads; otherwise whatever stands in for it, children, or initials, or the initials derived from name; and failing all of those, a silhouette.

Which one is showing is Base UI's Avatar to decide, because "has the image loaded" is a question with four answers and a race in the middle of it.

Which one is showing is decided by the Image itself: its frameBuilder shows the fallback until the first frame arrives, and its errorBuilder shows it for good if none ever does. There is no loading enum, because a picture that has not arrived and a picture that never will are the same case for as long as they last.

There is no delay. It exists in the React build so the initials do not flash up in front of a cached image; here a picture already in the image cache is decoded synchronously and the fallback is never built at all.

The derivation is the first character of the first word plus the first character of the last. "Jane Doe" is JD. A single-token name gives one character, because two characters of a Korean, Japanese or Chinese name at 40px is a smudge where one is a name.

React

import { PlAvatar } from 'plass-ui';

export default function AvatarFallback() {
  return (
    <div className="flex flex-wrap items-center gap-6 text-center">
      <div className="flex flex-col items-center gap-2">
        <PlAvatar name="Nadia Rowan" src="/samples/avatars/nadia-rowan.webp" />
        <span className="text-xs text-(--plass-muted-fg)">picture</span>
      </div>
      <div className="flex flex-col items-center gap-2">
        <PlAvatar name="Nadia Rowan" src="https://example.invalid/missing.png" />
        <span className="text-xs text-(--plass-muted-fg)">initials</span>
      </div>
      <div className="flex flex-col items-center gap-2">
        <PlAvatar name="Nadia Rowan" initials="NR!" />
        <span className="text-xs text-(--plass-muted-fg)">initials, written</span>
      </div>
      <div className="flex flex-col items-center gap-2">
        <PlAvatar name="Cat">🐈</PlAvatar>
        <span className="text-xs text-(--plass-muted-fg)">children</span>
      </div>
      <div className="flex flex-col items-center gap-2">
        <PlAvatar />
        <span className="text-xs text-(--plass-muted-fg)">silhouette</span>
      </div>
    </div>
  );
}

import 'package:flutter/widgets.dart';
import 'package:plass_ui/plass_ui.dart';

class AvatarFallback extends StatelessWidget {
  const AvatarFallback({super.key});

  @override
  Widget build(BuildContext context) {
    return const Wrap(
      spacing: 24,
      runSpacing: 24,
      crossAxisAlignment: WrapCrossAlignment.center,
      children: <Widget>[
        _Case(
          label: 'picture',
          child: PlAvatar(
            name: 'Nadia Rowan',
            image: NetworkImage('/samples/avatars/nadia-rowan.webp'),
          ),
        ),
        _Case(
          label: 'initials',
          // A provider that will never produce pixels, which is the case an
          // avatar has to survive rather than the one it hopes for.
          child: PlAvatar(name: 'Nadia Rowan', image: NetworkImage('https://example.invalid/x')),
        ),
        _Case(
          label: 'initials, written',
          child: PlAvatar(name: 'Nadia Rowan', initials: 'NR!'),
        ),
        _Case(
          label: 'child',
          child: PlAvatar(name: 'Cat', child: Text('🐈')),
        ),
        _Case(label: 'silhouette', child: PlAvatar()),
      ],
    );
  }
}

class _Case extends StatelessWidget {
  const _Case({required this.label, required this.child});

  final String label;
  final Widget child;

  @override
  Widget build(BuildContext context) {
    return Column(
      mainAxisSize: MainAxisSize.min,
      spacing: 8,
      children: <Widget>[
        child,
        PlTypography(label, level: PlTypographyLevel.caption),
      ],
    );
  }
}

variant

An avatar is the thing being coloured, a portrait of one particular person, so its sheet takes the tint, as a PlAlert's does and unlike a PlCard's. The edge is the neutral hairline rather than the sheet's own white one: an avatar is very often laid on something opaque, where white light on a cut edge is a claim about a page wash that is not behind it.

ghost is the default rather than solid, which is the other way round from a PlButton. A directory is a page of avatars, and a page of saturated circles is a page nobody can read a name off.

React

import { PlAvatar } from 'plass-ui';

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

import 'package:flutter/widgets.dart';
import 'package:plass_ui/plass_ui.dart';

class AvatarVariants extends StatelessWidget {
  const AvatarVariants({super.key});

  @override
  Widget build(BuildContext context) {
    return Wrap(
      spacing: 16,
      runSpacing: 16,
      crossAxisAlignment: WrapCrossAlignment.center,
      children: <Widget>[
        for (final variant in PlassVariant.values)
          PlAvatar(size: PlassSize.lg, variant: variant, name: 'Jane Doe'),
      ],
    );
  }
}

shape

circle is the default, because that is what a portrait has been for as long as there have been portraits. square takes the library's own fillet instead, which is what a logo or a repository icon wants. Those are drawn to the edges of a rectangle and a round crop eats them.

React

import { PlAvatar } from 'plass-ui';

export default function AvatarShapes() {
  return (
    <div className="flex flex-wrap items-center gap-4">
      <PlAvatar size="lg" name="Theo Quinn" src="/samples/avatars/theo-quinn.webp" />
      <PlAvatar size="lg" shape="square" name="Theo Quinn" src="/samples/avatars/theo-quinn.webp" />
    </div>
  );
}

import 'package:flutter/widgets.dart';
import 'package:plass_ui/plass_ui.dart';

class AvatarShapes extends StatelessWidget {
  const AvatarShapes({super.key});

  @override
  Widget build(BuildContext context) {
    return const Wrap(
      spacing: 16,
      runSpacing: 16,
      crossAxisAlignment: WrapCrossAlignment.center,
      children: <Widget>[
        PlAvatar(
          size: PlassSize.lg,
          name: 'Theo Quinn',
          image: NetworkImage('/samples/avatars/theo-quinn.webp'),
        ),
        PlAvatar(
          size: PlassSize.lg,
          shape: PlAvatarShape.square,
          name: 'Theo Quinn',
          image: NetworkImage('/samples/avatars/theo-quinn.webp'),
        ),
      ],
    );
  }
}

size

The control heights, so an avatar and the button beside it in a toolbar sit on the same baseline.

React

import { PlAvatar } from 'plass-ui';

export default function AvatarSizes() {
  return (
    <div className="flex flex-wrap items-center gap-4">
      {(['xs', 'sm', 'md', 'lg', 'xl'] as const).map((size) => (
        <PlAvatar key={size} size={size} name="Anya Sol" src="/samples/avatars/anya-sol.webp" />
      ))}
    </div>
  );
}

import 'package:flutter/widgets.dart';
import 'package:plass_ui/plass_ui.dart';

class AvatarSizes extends StatelessWidget {
  const AvatarSizes({super.key});

  @override
  Widget build(BuildContext context) {
    return Wrap(
      spacing: 16,
      runSpacing: 16,
      crossAxisAlignment: WrapCrossAlignment.center,
      children: <Widget>[
        for (final size in PlassSize.values) PlAvatar(size: size, name: 'Jane Doe'),
      ],
    );
  }
}

color

React

import { PlAvatar } from 'plass-ui';

export default function AvatarColors() {
  return (
    <div className="flex flex-wrap items-center gap-4">
      {(['primary', 'secondary', 'success', 'warning', 'danger', 'info'] as const).map((color) => (
        <PlAvatar key={color} color={color} name={color} />
      ))}
    </div>
  );
}

import 'package:flutter/widgets.dart';
import 'package:plass_ui/plass_ui.dart';

class AvatarColors extends StatelessWidget {
  const AvatarColors({super.key});

  @override
  Widget build(BuildContext context) {
    return Wrap(
      spacing: 16,
      runSpacing: 16,
      crossAxisAlignment: WrapCrossAlignment.center,
      children: <Widget>[
        for (final color in PlassColor.values) PlAvatar(color: color, name: color.name),
      ],
    );
  }
}

A stack of them

A stack of overlapping faces with a +n on the end is a PlStack with avatars in it. It is a general pile rather than an avatar component, so it sets no axes on what it holds. Put a PlassProvider around it for size and color, and write the rest on the avatars.

Accessibility

• The picture takes alt, falling back to name, falling back to an empty alt. Empty rather than absent: an avatar beside the person's own name in a row is decoration, and alt left off is what makes a screen reader read the file name out instead.
• JD read out loud is two letters, not a person. When there is a name it becomes the fallback's accessible name and the initials are hidden as the picture they are standing in for.
• A silhouette says nothing at all. There is no name to announce, and "graphic" is not information.
• An avatar that is also a link or a button has to be one: put it inside a real <a> or <button> and give that element the name.

• The avatar takes semanticLabel, falling back to name, falling back to nothing at all. Nothing rather than a guess: an avatar beside the person's own name in a row is decoration, and saying the name twice is worse than saying it once.
• JD read out loud is two letters, not a person. When there is a name it becomes the accessible name and the initials are excluded as the picture they are standing in for. With no name the initials are all there is, and they are read.
• A silhouette says nothing at all. There is no name to announce, and "graphic" is not information.
• An avatar that is also a link or a button belongs inside one: a PlButton or a PlCard with onPressed, named there.

Differences from the React build

React	Flutter	Why
src / srcSet / imageProps	image	An ImageProvider is the shape every image in Flutter has, and it already covers resolution variants, headers and caching.
alt	semanticLabel	Flutter's name. It names the avatar rather than an inner element, because there is no inner element to name.
delay	—	A cached image decodes synchronously here, so the fallback never flashes and there is nothing to wait out.
onLoadingStatusChange	—	There is no four-state machine to report: the fallback is shown until a frame arrives and for good if none does. An ImageProvider's own ImageStream is where a caller who needs the states goes.
children	child	Flutter's name.
className, style	—	There is no class list and no style attribute to pass through.