The avatar component is used to represent a user or entity with an image, icon, or initials
Example
Basic avatar usage with icon, text initials, and image content options
code
<script type="module">
import '@blueprintui/components/include/avatar.js';
import '@blueprintui/icons/shapes/user.js';
</script>
<div bp-layout="inline gap:sm">
<bp-avatar aria-label="User avatar">
<bp-icon shape="user" type="solid"></bp-icon>
</bp-avatar>
<bp-avatar aria-label="John Doe">JD</bp-avatar>
<bp-avatar>
<img src="/assets/images/browsers/chrome.svg" alt="chrome browser" loading="lazy" />
</bp-avatar>
</div>Shapes
Avatar shape variants including circle (default), square, and rounded styles
code
<script type="module">
import '@blueprintui/components/include/avatar.js';
import '@blueprintui/icons/shapes/user.js';
</script>
<div bp-layout="inline gap:sm">
<bp-avatar aria-label="default avatar"></bp-avatar>
<bp-avatar shape="square" aria-label="square avatar"></bp-avatar>
<bp-avatar shape="rounded" aria-label="rounded avatar"></bp-avatar>
</div>Status
Status indicators for user presence or state using accent, success, warning, and danger colors
code
<script type="module">
import '@blueprintui/components/include/avatar.js';
</script>
<div bp-layout="inline gap:sm">
<bp-avatar aria-label="Default user"></bp-avatar>
<bp-avatar status="accent" aria-label="User with accent status"></bp-avatar>
<bp-avatar status="success" aria-label="Online user"></bp-avatar>
<bp-avatar status="warning" aria-label="User with warning"></bp-avatar>
<bp-avatar status="danger" aria-label="User with danger status"></bp-avatar>
</div>Sizes
Custom avatar sizing using CSS variables with small, medium, and large examples
code
<script type="module">
import '@blueprintui/components/include/avatar.js';
</script>
<div bp-layout="inline gap:sm">
<bp-avatar aria-label="small avatar" style="--size: var(--bp-size-700)"></bp-avatar>
<bp-avatar aria-label="medium avatar"></bp-avatar>
<bp-avatar aria-label="large avatar" style="--size: var(--bp-size-900)"></bp-avatar>
</div>Initials
Text-based avatars displaying user initials as content for multiple users
code
<script type="module">
import '@blueprintui/components/include/avatar.js';
</script>
<div bp-layout="inline gap:sm">
<bp-avatar aria-label="John Doe">JD</bp-avatar>
<bp-avatar aria-label="Sarah Smith">SS</bp-avatar>
<bp-avatar aria-label="Mike Johnson">MJ</bp-avatar>
<bp-avatar aria-label="Emily Brown">EB</bp-avatar>
</div>Images
Image-based avatars using the default slot for custom graphics or photos
code
<script type="module">
import '@blueprintui/components/include/avatar.js';
</script>
<div bp-layout="inline gap:sm">
<bp-avatar>
<img src="/assets/images/browsers/safari.svg" alt="safari browser" loading="lazy" />
</bp-avatar>
<bp-avatar>
<img src="/assets/images/browsers/firefox.svg" alt="firefox browser" loading="lazy" />
</bp-avatar>
<bp-avatar>
<img src="/assets/images/browsers/edge.svg" alt="edge browser" loading="lazy" />
</bp-avatar>
<bp-avatar>
<img src="/assets/images/browsers/chrome.svg" alt="chrome browser" loading="lazy" />
</bp-avatar>
</div>Icons
Icon-based avatars demonstrating different entity types like users, organizations, teams, and settings
code
<script type="module">
import '@blueprintui/components/include/avatar.js';
import '@blueprintui/icons/include.js';
import '@blueprintui/icons/shapes/user.js';
import '@blueprintui/icons/shapes/building.js';
import '@blueprintui/icons/shapes/employee-group.js';
import '@blueprintui/icons/shapes/cog.js';
</script>
<div bp-layout="inline gap:sm">
<bp-avatar aria-label="User">
<bp-icon shape="user" type="solid"></bp-icon>
</bp-avatar>
<bp-avatar aria-label="Organization">
<bp-icon shape="building" type="solid"></bp-icon>
</bp-avatar>
<bp-avatar aria-label="Team">
<bp-icon shape="employee-group" type="solid"></bp-icon>
</bp-avatar>
<bp-avatar aria-label="Settings">
<bp-icon shape="cog" type="solid"></bp-icon>
</bp-avatar>
</div>Group
Stacked avatar group pattern with overlapping layout and overflow count indicator
code
<script type="module">
import '@blueprintui/components/include/avatar.js';
</script>
<div class="avatar-group" bp-layout="inline">
<bp-avatar>
<img src="/assets/images/browsers/safari.svg" alt="safari browser" loading="lazy" />
</bp-avatar>
<bp-avatar>
<img src="/assets/images/browsers/firefox.svg" alt="firefox browser" loading="lazy" />
</bp-avatar>
<bp-avatar>
<img src="/assets/images/browsers/chrome.svg" alt="chrome browser" loading="lazy" />
</bp-avatar>
<bp-avatar aria-label="More users">+5</bp-avatar>
</div>
<style>
.avatar-group bp-avatar:not(:last-of-type) {
margin-right: calc(-1 * var(--bp-space-xs));
}
</style>Install
NPM
// npm package
import '@blueprintui/components/include/avatar.js';CDN
<script type="module">
import 'https://cdn.jsdelivr.net/npm/@blueprintui/components/include/avatar.js/+esm';
</script>Accessibility
- When slotting an
<img>, use thealtattribute for accessibility - For non-image content (initials, icons), use the standard
aria-labelattribute on<bp-avatar>for accessibility - Image loading behavior (lazy/eager) is controlled via the standard
loadingattribute on the slotted<img>tag - The component automatically sets
role="img"for proper semantics
bp-avatar
Properties
| Name | Types | Description |
|---|---|---|
shape | 'square' | 'rounded' | determine the visual shape of the avatar |
status | 'accent' | 'success' | 'warning' | 'danger' | optional status indicator color |
Attributes
| Name | Types | Description |
|---|---|---|
shape | 'square' | 'rounded' | determine the visual shape of the avatar |
status | 'accent' | 'success' | 'warning' | 'danger' | optional status indicator color |
CSS Properties
| Name | Types | Description |
|---|---|---|
--size | Size of the avatar (default: var(--bp-size-900)) | |
--background | Background color | |
--color | Text/icon color | |
--border-radius | Border radius (controlled by shape attribute) |
Slots
| Name | Types | Description |
|---|---|---|
default | Content to display - text for initials, img for image, or icon for custom icon |