Avatar

The Avatar component is used to represent a user, and displays the profile picture, initials or fallback icon.

Installation

npm

npm add @heroui-vue/avatar

pnpm

pnpm add @heroui-vue/avatar

yarn

yarn add @heroui-vue/avatar

bun

bun add @heroui-vue/avatar

NOTE

If you use global installation, you can skip this step.

Import

HeroUI Vue currently exports 2 avatar-related components:

• Avatar: The main component to display an avatar.
• AvatarGroup: A wrapper component to display a group of avatars.

AvatarIcon is still not exported as a standalone component in HeroUI Vue. You can use the built-in fallback icon or provide a custom icon.

On-demand import

import { Avatar, AvatarGroup } from '@heroui-vue/avatar'

Global import

import { Avatar, AvatarGroup } from 'heroui-vue'

Usage

PreviewSource Code

JJJ

Sizes

PreviewSource Code

Disabled

PreviewSource Code

JJJ

Bordered

PreviewSource Code

Radius

PreviewSource Code

Colors

PreviewSource Code

Avatar Fallbacks

If there is an error loading the src of the avatar, there are 2 fallbacks:

• If there's a name prop, we use it to generate the initials.
• If there's no name prop, we use a default avatar icon.

If showFallback is not passed, the fallbacks will not be displayed.

PreviewSource Code

Custom Fallback

You can also provide a custom fallback component to be displayed when the src fails to load.

PreviewSource Code

Custom Implementation

In case you need to customize avatar behavior further, HeroUI Vue currently keeps useAvatar as an internal composition utility and does not expose it as a stable public API yet.

Custom initials logic

HeroUI React supports getInitials for custom initials logic. HeroUI Vue does not expose this prop yet; by default initials are derived from the first characters of up to two words in name.

Avatar Group

PreviewSource Code

Group Disabled

PreviewSource Code

Group Max Count

You can limit the number of avatars displayed by passing the max prop to the AvatarGroup component.

PreviewSource Code

+3

Group Total Count

You can display the total number of avatars by passing the total prop to the AvatarGroup component.

PreviewSource Code

+7

Group Custom count

HeroUI React supports renderCount as a render function. HeroUI Vue currently supports renderCount as a boolean switch to show/hide the built-in count badge.

PreviewSource Code

Group Grid

By passing the isGrid prop to the AvatarGroup component, avatars will be displayed in a grid layout.

PreviewSource Code

+2

Group Custom Implementation

In case you need lower-level customization, HeroUI React exposes useAvatarGroup and AvatarGroupProvider. HeroUI Vue has not exposed equivalent public APIs yet.

Slots

• base: Avatar wrapper, it includes styles for focus ring, position, and general appearance.
• img: Image element within the avatar, it includes styles for opacity transition and size.
• fallback: Fallback content when the image fails to load or is not provided, it includes styles for centering the content.
• name: Initials displayed when the image is not provided or fails to load, it includes styles for font and text alignment.
• icon: Icon element within the avatar, it includes styles for centering the content and size.

Custom Avatar Styles

You can customize any part of the avatar by using the classNames prop.

PreviewSource Code

Data Attributes

Avatar has the following attributes on the base element:

• data-hover: When the avatar is being hovered.
• data-focus: When the avatar is being focused.
• data-focus-visible: When the avatar is being focused with keyboard navigation.

API

Avatar Props

Name	Type	Default	Description
src	string	-	The source URL of the image to be displayed.
color	"default" | "primary" | "secondary" | "success" | "warning" | "danger"	"default"	Sets the avatar background color.
radius	"none" | "sm" | "md" | "lg" | "full"	"full"	Sets the avatar border radius.
size	"sm" | "md" | "lg"	"md"	Sets the avatar size.
name	string	-	Displays initials if the image is not provided or fails to load.
icon	any	-	Displays a custom icon inside the avatar fallback.
fallback	any	-	A custom fallback component to display when the image fails to load.
isBordered	boolean	false	If true, adds a border around the avatar.
isDisabled	boolean	false	If true, disables the avatar and applies disabled styling.
isFocusable	boolean	false	If true, makes the avatar focusable for keyboard navigation.
showFallback	boolean	false	If true, shows fallback icon/initials when image fails to load.
imgProps	ImgHTMLAttributes	-	Props passed to the internal image element.
classNames	Partial<Record<"base" | "img" | "fallback" | "name" | "icon", string>>	-	Custom class names for avatar slots.

Avatar Group Props

Name	Type	Default	Description
max	number	-	The maximum number of visible avatars.
total	number	-	Controls the number of avatars not visible.
isGrid	boolean	false	Whether avatars should be displayed in a grid.
renderCount	boolean	true	Whether to render the built-in count badge.
classNames	Partial<Record<"base" | "count", string>>	-	Custom class names for avatar group slots.