Data display

Avatar

An image and fallback primitive for representing a person or entity.

AvatarView source

Example

The preview is interactive. The code below it is the docs demo source; demo-only layout classes can be omitted in application code.

tsx

import { Avatar, AvatarGroup, type AvatarItem } from "innate-ui";
import classes from "../docs.module.css";

const projectMembers: ReadonlyArray<AvatarItem> = [
  { id: "ada", name: "Ada Lovelace", status: "online" },
  { id: "grace", name: "Grace Hopper", src: "/favicon.svg", status: "away" },
  { id: "alan", name: "Alan Turing", src: "/missing-avatar.png", status: "busy" },
  { id: "katherine", name: "Katherine Johnson" },
  { id: "margaret", name: "Margaret Hamilton" },
];

export function AvatarDemo() {
  return (
    <div class={classes.avatarDemo}>
      <div class={classes.avatarRow}>
        <Avatar name="Innate mark" src="/favicon.svg" size="large" status="online" />
        <Avatar name="Ada Lovelace" decoration={<span class={classes.avatarDecoration}>✓</span>} />
        <Avatar name="Margaret Hamilton" src="/missing-avatar.png" size="small" />
      </div>
      <AvatarGroup
        items={projectMembers}
        label="Project members"
        limit={3}
        total={5}
        size="medium"
      />
    </div>
  );
}

API reference

This table is generated from Innate UI's exported TypeScript declarations and JSDoc. Native element attributes inherited by a prop type are not repeated here.

AvatarProps

Prop	Type	Default
`name`required Person or entity name used for accessible text and generated initials.	`JSX.ValueOrCell<string>`	`—`
`src` Image source. Falls back to initials when absent or when loading fails.	`JSX.ValueOrCell<string \| null \| undefined>`	`—`
`fallback` Custom fallback content rendered instead of generated initials.	`JSX.Children`	`—`
`size` Avatar size.	`JSX.ValueOrCell<AvatarSize>`	`"medium"`
`status` Optional presence status shown on the avatar.	`JSX.ValueOrCell<AvatarStatus \| null \| undefined>`	`—`
`statusLabel` Accessible label for the status indicator. Defaults to the status name.	`JSX.ValueOrCell<string \| null \| undefined>`	`—`
`decoration` Optional decoration rendered on the avatar.	`JSX.Children`	`—`
`decorative` Removes the avatar from the accessibility tree when purely decorative.	`JSX.ValueOrCell<boolean>`	`false`
`loading` Native image loading strategy.	`JSX.ValueOrCell<AvatarImageLoading>`	`"lazy"`
`imageProps` Additional props forwarded to the internal image element.	`AvatarImageProps`	`—`
`imageRef` Receives the internal image element.	`SourceCell<HTMLImageElement \| null>`	`—`

AvatarGroupProps

Prop	Type	Default
`items`required Avatars rendered by the group.	`JSX.ValueOrCell<ReadonlyArray<AvatarItem>>`	`—`
`label`required Accessible label describing the group.	`JSX.ValueOrCell<string>`	`—`
`size` Size applied to every avatar in the group.	`JSX.ValueOrCell<AvatarSize>`	`"medium"`
`limit` Maximum number of avatars shown before the overflow indicator.	`JSX.ValueOrCell<number>`	`4`
`total` Total member count when it differs from `items.length`.	`JSX.ValueOrCell<number \| null \| undefined>`	`—`
`renderOverflow` Custom renderer for the number of hidden members.	`(count: number) => JSX.Template`	`—`

Inspect the typed source →