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.
<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.
<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.
<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.
<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.
<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.
<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 circleoffline— gray rounded squarebusy— red rounded squareaway— yellow circle
Because the status is conveyed purely through color and shape, provide a statusLabel (e.g. Online) so assistive technologies can announce it.
<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.
<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.
<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.
<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.
<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><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 variable | Default |
|---|---|
--bs-avatar-size | 2.5rem |
--bs-avatar-border-radius | 50% |
--bs-avatar-border-width | 2px |
--bs-avatar-border-color | var(--bs-bg-body) |
--bs-avatar-bg | var(--bs-bg-2) |
--bs-avatar-color | var(--bs-fg-body) |
--bs-avatar-status-size | 0.75rem |
--bs-avatar-status-border-width | 2px |
--bs-avatar-status-border-color | var(--bs-bg-body) |
--bs-avatar-stack-spacing | -0.3 |
--bs-avatar-stack-transition | transform .2s ease-in-out |