Avatar

Avatars represent users and organizations.

Usage

To display an avatar, wrap text in an <Avatar>. By default, only the first letter will display.

import { Avatar } from "stylus-ui/Avatar";

export default () => <Avatar>Aaron Podolny</Avatar>;

Images

To display an image, simply wrap an img element in Avatar. Remember to set alt text!

import { Avatar } from "stylus-ui/Avatar";

export default () => {
  return (
    <Avatar size="xl">
      <img
        src="https://api.dicebear.com/9.x/micah/png"
        alt="A user avatar"
        className="w-full"
      />
    </Avatar>
  );
};

Icons

Sometimes it's helpful to display an icon within an avatar, for example, when offering a way to invite a new user. To display an icon, import Icon and wrap it within Avatar. If the avatar is used without a nearby description, always add a title to Icon to render it accessible to screen readers.

import { Avatar } from "stylus-ui/Avatar";
import { Icon } from "stylus-ui/Icon";
import { faPlus } from "@fortawesome/pro-regular-svg-icons";

export default () => {
  return (
    <Avatar>
      <Icon icon={faPlus} className="size-4" title="Invite user" />
    </Avatar>
  );
};

Shapes

Avatars can display as square. Use circular avatars for individuals and square avatars for organizations or groups.

import { Avatar } from "stylus-ui/Avatar";

export default () => <Avatar shape="square">Acme Inc</Avatar>;

Colors

Avatars can be styled with a color. Under the brand refresh, the legacy palette collapses onto five accent colors, so this example shows one avatar per distinct color when the flag is on (and the full legacy set when it is off).

import { Avatar } from "stylus-ui/Avatar";
import { useEffect, useState } from "react";

const legacyColors = [
  "orange",
  "yellow",
  "lime",
  "emerald",
  "cyan",
  "blue",
  "violet",
  "fuchsia",
  "rose",
  "gray",
];

// The brand refresh maps the legacy palette onto 5 accent colors — showing one
// avatar per legacy color would render visual duplicates, so show one per accent.
const brandRefreshColors = ["blue", "orange", "violet", "yellow", "emerald"];

export default () => {
  const [colors, setColors] = useState(legacyColors);

  useEffect(() => {
    const root = document.documentElement;
    const sync = () =>
      setColors(
        root.classList.contains("brand-refresh-tokens")
          ? brandRefreshColors
          : legacyColors,
      );

    sync();
    const observer = new MutationObserver(sync);
    observer.observe(root, { attributes: true, attributeFilter: ["class"] });

    return () => observer.disconnect();
  }, []);

  return (
    <div className="flex flex-wrap gap-2">
      {colors.map((color) => (
        <Avatar key={color} color={color}>
          {color}
        </Avatar>
      ))}
    </div>
  );
};

Automatic colors

To set the color automatically, pass a uuid. Commonly, this will be a userId.

import { Avatar } from "stylus-ui/Avatar";

// Fetch your user data
const exampleUser = {
  name: "Emily Moreton",
  userId: "1234567890",
};

export default () => (
  // Use `userId` (or another unique identifier) to set the avatar color
  <Avatar uuid={exampleUser.userId}>{exampleUser.name}</Avatar>
);

Anonymous users

If a user is unknown, import AnonymousAvatar instead of Avatar. AnonymousAvatar takes an icon prop to display an icon from Font Awesome. You don't have to import the icon; just pass in a string.

import { AnonymousAvatar } from "stylus-ui/Avatar";

export default () => <AnonymousAvatar icon="faUser" />;

Anonymous users with color background

import { AnonymousAvatar } from "stylus-ui/Avatar";

export default () => <AnonymousAvatar icon="faUser" color="violet" />;

Groups

To display a group of avatars together, wrap Avatars in an AvatarGroup.

API Reference

`Avatar`

Avatars represent users and organizations.

`color`

Background color for initials; ignored when children is an image.

`shape`

"circle" | "square" = "circle"

Shape of the avatar: circle or square.

`size`

"xxs" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "3xl" = "md"

Size from xxs (16px) to 3xl (96px).

`uuid`

string

When set, color is derived from this value for consistent per-user colors.

`AnonymousAvatar`

AnonymousAvatar is used to represent users who are not logged in.

`icon`

Required

`color`

`size`

"xxs" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "3xl" = "md"