Loading...
Skip to main content

Avatar

Documentation and examples for avatars, including image avatars, initials, status indicators, and avatar stacks.

Use Avatar for images, initials, and status indicators, AvatarImage for a standalone image, and AvatarStack for overlapping groups. Set size, theme, subtle, and status to configure the avatar appearances described below.

Examples

Avatars are used to represent users or entities. They can display an image or initials as a fallback.

Image

Use Avatar with AvatarImage for image-based avatars. The parent Avatar element provides an easy wrapper for additional avatar features like status indicators and stacks. You’re welcome to use AvatarImage on its own if you only need a single HTML element.

mdo
<div className="d-flex flex-wrap gap-2 align-items-center">
<Avatar
alt="mdo"
src="https://github.com/mdo.png"
/>
</div>

When used inside the Avatar wrapper, the image fills the wrapper and its size is set with --bs-avatar-size. Used on its own, AvatarImage honors its own width and height instead, so set them to your desired size.

mdo
<div className="d-flex flex-wrap gap-2 align-items-center">
<AvatarImage
alt="mdo"
height="50"
src="https://github.com/mdo.png"
width="50"
/>
</div>

Initials

Use text content inside Avatar for initials-based avatars.

ABCDEFGGGHIJKLMNOP
<div className="d-flex flex-wrap gap-2 align-items-center">
<Avatar>
AB
</Avatar>
<Avatar theme="primary">
CD
</Avatar>
<Avatar theme="accent">
EF
</Avatar>
<Avatar theme="success">
GG
</Avatar>
<Avatar theme="danger">
GH
</Avatar>
<Avatar theme="warning">
IJ
</Avatar>
<Avatar theme="info">
KL
</Avatar>
<Avatar theme="inverse">
MN
</Avatar>
<Avatar theme="secondary">
OP
</Avatar>
</div>

Set the subtle prop to create a subtle avatar.

ABCDEFGGGHIJKLMNOP
<div className="d-flex flex-wrap gap-2 align-items-center">
<Avatar>
AB
</Avatar>
<Avatar
subtle
theme="primary"
>
CD
</Avatar>
<Avatar
subtle
theme="accent"
>
EF
</Avatar>
<Avatar
subtle
theme="success"
>
GG
</Avatar>
<Avatar
subtle
theme="danger"
>
GH
</Avatar>
<Avatar
subtle
theme="warning"
>
IJ
</Avatar>
<Avatar
subtle
theme="info"
>
KL
</Avatar>
<Avatar
subtle
theme="inverse"
>
MN
</Avatar>
<Avatar
subtle
theme="secondary"
>
OP
</Avatar>
</div>

Sizes

Avatars come in multiple sizes: extra small, small, default, large, and extra large.

mdomdomdomdomdo
<div className="d-flex flex-wrap gap-2 align-items-center">
<Avatar
alt="mdo"
size="xs"
src="https://github.com/mdo.png"
/>
<Avatar
alt="mdo"
size="sm"
src="https://github.com/mdo.png"
/>
<Avatar
alt="mdo"
src="https://github.com/mdo.png"
/>
<Avatar
alt="mdo"
size="lg"
src="https://github.com/mdo.png"
/>
<Avatar
alt="mdo"
size="xl"
src="https://github.com/mdo.png"
/>
</div>

Use a custom size by modifying the --bs-avatar-size variable. The numeric size prop sets it in rem.

mdo
<div className="d-flex flex-wrap gap-2 align-items-center">
<Avatar
alt="mdo"
size={8}
src="https://github.com/mdo.png"
/>
</div>

Status indicator

Set the status prop to show an indicator inside the avatar. Each status has a distinct shape and color:

  • online — green circle
  • offline — gray rounded square
  • busy — red rounded square
  • away — yellow circle

Because the status is conveyed purely through color and shape, provide a statusLabel (e.g. Online) so assistive technologies can announce it.

mdomdomdomdo
<div className="d-flex flex-wrap gap-2 align-items-center">
<Avatar
alt="mdo"
src="https://github.com/mdo.png"
status="online"
statusLabel="Online"
/>
<Avatar
alt="mdo"
src="https://github.com/mdo.png"
status="offline"
statusLabel="Offline"
/>
<Avatar
alt="mdo"
src="https://github.com/mdo.png"
status="busy"
statusLabel="Busy"
/>
<Avatar
alt="mdo"
src="https://github.com/mdo.png"
status="away"
statusLabel="Away"
/>
</div>

Status with sizes

The status indicator scales with the avatar size.

mdomdomdomdomdo
<div className="d-flex flex-wrap gap-2 align-items-center">
<Avatar
alt="mdo"
size="xs"
src="https://github.com/mdo.png"
status="online"
statusLabel="Online"
/>
<Avatar
alt="mdo"
size="sm"
src="https://github.com/mdo.png"
status="online"
statusLabel="Online"
/>
<Avatar
alt="mdo"
src="https://github.com/mdo.png"
status="online"
statusLabel="Online"
/>
<Avatar
alt="mdo"
size="lg"
src="https://github.com/mdo.png"
status="online"
statusLabel="Online"
/>
<Avatar
alt="mdo"
size="xl"
src="https://github.com/mdo.png"
status="online"
statusLabel="Online"
/>
</div>

Avatar stack

Use AvatarStack to group multiple avatars together with overlapping effect. Avatars are rendered in reverse order so the first avatar appears on top. Stacks use a percentage of the avatar size to determine how much to overlap stacked avatars.

mdomdomdomdomdo
<div className="d-flex flex-wrap gap-2 align-items-center">
<AvatarStack>
<Avatar
alt="mdo"
src="https://github.com/mdo.png"
/>
<Avatar
alt="mdo"
src="https://github.com/mdo.png"
/>
<Avatar
alt="mdo"
src="https://github.com/mdo.png"
/>
<Avatar
alt="mdo"
src="https://github.com/mdo.png"
/>
<Avatar
alt="mdo"
src="https://github.com/mdo.png"
/>
</AvatarStack>
</div>

Stack with sizes

As a shorthand, size props are available for AvatarStack and Avatar.

mdomdomdo
mdomdomdo
mdomdomdo
mdomdomdo
mdomdomdo
<Stack
className="align-items-start"
gap={3}
>
<AvatarStack size="xs">
<Avatar
alt="mdo"
src="https://github.com/mdo.png"
/>
<Avatar
alt="mdo"
src="https://github.com/mdo.png"
/>
<Avatar
alt="mdo"
src="https://github.com/mdo.png"
/>
</AvatarStack>
<AvatarStack size="sm">
<Avatar
alt="mdo"
src="https://github.com/mdo.png"
/>
<Avatar
alt="mdo"
src="https://github.com/mdo.png"
/>
<Avatar
alt="mdo"
src="https://github.com/mdo.png"
/>
</AvatarStack>
<AvatarStack>
<Avatar
alt="mdo"
src="https://github.com/mdo.png"
/>
<Avatar
alt="mdo"
src="https://github.com/mdo.png"
/>
<Avatar
alt="mdo"
src="https://github.com/mdo.png"
/>
</AvatarStack>
<AvatarStack size="lg">
<Avatar
alt="mdo"
src="https://github.com/mdo.png"
/>
<Avatar
alt="mdo"
src="https://github.com/mdo.png"
/>
<Avatar
alt="mdo"
src="https://github.com/mdo.png"
/>
</AvatarStack>
<AvatarStack size="xl">
<Avatar
alt="mdo"
src="https://github.com/mdo.png"
/>
<Avatar
alt="mdo"
src="https://github.com/mdo.png"
/>
<Avatar
alt="mdo"
src="https://github.com/mdo.png"
/>
</AvatarStack>
</Stack>

Stack with count

Combine with initials to show a count of additional users.

mdomdomdo+5
<div className="d-flex flex-wrap gap-2 align-items-center">
<AvatarStack>
<Avatar
alt="mdo"
src="https://github.com/mdo.png"
/>
<Avatar
alt="mdo"
src="https://github.com/mdo.png"
/>
<Avatar
alt="mdo"
src="https://github.com/mdo.png"
/>
<Avatar theme="secondary">
+5
</Avatar>
</AvatarStack>
</div>
mdomdomdo+5
<div className="d-flex flex-wrap gap-2 align-items-center">
<AvatarStack size="xl">
<Avatar
alt="mdo"
src="https://github.com/mdo.png"
/>
<Avatar
alt="mdo"
src="https://github.com/mdo.png"
/>
<Avatar
alt="mdo"
src="https://github.com/mdo.png"
/>
<Avatar theme="secondary">
+5
</Avatar>
</AvatarStack>
</div>

CSS

Variables

Customize the component with the following local CSS variables. Override them through the wrapper’s style prop or your own CSS module.

CSS variableDefault
--bs-avatar-size2.5rem
--bs-avatar-border-radius50%
--bs-avatar-border-width2px
--bs-avatar-border-colorvar(--bs-bg-body)
--bs-avatar-bgvar(--bs-bg-2)
--bs-avatar-colorvar(--bs-fg-body)
--bs-avatar-status-size0.75rem
--bs-avatar-status-border-width2px
--bs-avatar-status-border-colorvar(--bs-bg-body)
--bs-avatar-stack-spacing-0.3
--bs-avatar-stack-transitiontransform .2s ease-in-out
Documentation navigation
On this page
On this page