Avatar Group

Stacks multiple avatars with overlapping borders and shows an overflow count badge when items exceed the max limit. Accepts image URLs or text initials as fallback.

free

Basic Avatar Group

Pass an array of AvatarGroupItem objects. Each item can have an avatarUrl, initials, and name.

HTML

TypeScript

Sizes

Control avatar size with the size input: xs, sm, md, lg, xl.

HTML

Overflow Count

Set max to limit visible avatars. The remaining count is shown as a +N chip.

HTML

Initials Fallback

If avatarUrl is omitted, the component shows initials or the first letter of name.

Installation

Run the following command to add this component to your project:

bash

npx base-ui-cli add avatar-group

API Reference

For AI agents

Copy a prompt with the registry name, CLI install, and import — or add the Base UI MCP server.

bash

npx -y base-ui-mcp

Base UI provides standalone components. Import the exact elements you want to use into your component.

typescript (Example)

// Install: npx base-ui-cli add avatar-group
// Paths are relative to aliases.components (default: src/app/components)
import { AvatarGroupComponent } from './avatar-group/avatar-group.component';

@Component({
  selector: 'app-your-component',
  imports: [
    AvatarGroupComponent
  ],
  template: `...`
})
export class YourComponent {}

API for avatar-group — generated from JSDoc in the library source.

API reference for avatar-group
API	Member	Type	Default	Description
`base-avatar-group`	`class`	`string`	`''`	Additional host CSS classes (merged via cn()).
`base-avatar-group`	`items`	`AvatarGroupItem[]`	`[]`	—
`base-avatar-group`	`max`	`number`	`4`	—
`base-avatar-group`	`size`	`AvatarSize`	`'md'`	—