Avatar Showcase

Use Avatar Showcase to present an ordered group of people with a moving avatar strip. It accepts a recent subset and a total count, so the visual can represent a larger community without loading every profile.

Preview

Reduce motion:Off

Tune:Off

Inspect

Installation

Motion

npx shadcn@latest add @sona-ui/avatar-showcase

Basic usage

community.tsx

import AvatarShowcase from "@/components/ui/avatar-showcase/avatar-showcase";
 
const people = [
{ name: "Maya Chen", imageUrl: "/maya.jpg" },
{ name: "Noah Patel", imageUrl: "/noah.jpg" },
];
 
export function Community() {
return <AvatarShowcase items={people} totalCount={1240} />;
}

Examples

Use lanes to adjust the density, and pass a totalCount when the displayed people are only a recent sample.

Usage


const FOLLOWERS: AvatarShowcaseItem[] = [
  { id: "1", name: "Maya Chen", imageUrl: "https://i.pravatar.cc/160?img=5" },
  {
    id: "2",
    name: "Noah Williams",
    imageUrl: "https://i.pravatar.cc/160?img=12",
  },
  {
    id: "3",
    name: "Aisha Rahman",
    imageUrl: "https://i.pravatar.cc/160?img=32",
  },
  { id: "4", name: "Leo Martin", imageUrl: "https://i.pravatar.cc/160?img=11" },
  {
    id: "5",
    name: "Sofia Silva",
    imageUrl: "https://i.pravatar.cc/160?img=47",
  },
  { id: "6", name: "Ethan Kim", imageUrl: "https://i.pravatar.cc/160?img=68" },
  {
    id: "7",
    name: "Amara Okafor",
    imageUrl: "https://i.pravatar.cc/160?img=44",
  },
  {
    id: "8",
    name: "Oliver Smith",
    imageUrl: "https://i.pravatar.cc/160?img=15",
  },
  { id: "9", name: "Priya Nair", imageUrl: "https://i.pravatar.cc/160?img=49" },
  {
    id: "10",
    name: "Mateo Garcia",
    imageUrl: "https://i.pravatar.cc/160?img=53",
  },
  { id: "11", name: "Hana Sato", imageUrl: "https://i.pravatar.cc/160?img=25" },
  { id: "12", name: "Jon Bell", imageUrl: "https://i.pravatar.cc/160?img=3" },
];
 
export default function AvatarShowcaseExample() {
  return (
    <AvatarShowcase
      items={FOLLOWERS}
      message="Thanks for following"
      totalCount={912}
    />
  );
}

API

Property	Type	Default	Description
`items`	`AvatarShowcaseItem[]`	`required`	Ordered people to present. The first item is treated as the most recent.
`lanes`	`1 \| 2 \| 3`	`1`	Number of vertically staggered lanes used by the moving strip.
`totalCount`	`number`	`items.length`	Total community size when `items` contains only a recent subset.
`message`	`string`	`undefined`	Optional message revealed with the final count. Omit it for a count-only ending.
`maxItems`	`number`	`80`	Maximum number of avatars rendered before deterministic sampling is applied.
`duration`	`number`	`undefined`	Fixed playback duration in seconds. When omitted, duration is derived from the total count.
`avatarSize`	`number`	`56`	Avatar diameter in pixels.
`onComplete`	`() => void`	`undefined`	Called after the strip finishes and the ending is revealed.

Accessibility

Provide names for people whenever they are available. Reduced-motion preferences show a static, readable avatar group.

Styling

Use className and the component options to fit the strip into a community, activity, or social-proof section.

Contact

Found a bug or need help using this component? Open an issue on GitHub.

License & Usage

Sona UI is available under the MIT license. You may use, modify, and distribute this component in personal and commercial projects.

Was this page helpful?

Your response helps us improve component docs.