Avatar

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

Installation

npx nextui-cli@latest add avatar

The above command is for individual installation only. You may skip this step if @nextui-org/react is already installed globally.

Import

NextUI exports 3 avatar-related components:

• Avatar: The main component to display an avatar.
• AvatarGroup: A wrapper component to display a group of avatars.
• AvatarIcon: The default icon used as fallback when the image fails to load.

Usage

Sizes

Disabled

Bordered

Radius

Colors

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 and a random, accessible background color.
• If there's no name prop, we use a default avatar.

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

Custom Fallback

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

Custom Implementation

In case you need to customize the avatar even further, you can use the useAvatar hook to create your own implementation.

Custom initials logic

It is possible to customize the logic used to generate the initials by passing a function to the getInitials prop. By default we merge the first characters of each word in the name prop.

Avatar Group

Group Disabled

Group Max Count

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

Group Total Count

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

Group Custom count

NextUI provides a renderCount prop to customize the count displayed when the total prop is passed.

Group Grid

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

Group Custom Implementation

In case you need to customize the avatar group even further, you can use the useAvatarGroup hook and the AvatarGroupProvider to create your own implementation.

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, text alignment, and inheritance.
• icon: Icon element within the avatar, it includes styles for centering the content, text inheritance, and size.

Custom Avatar Styles

You can customize any part of the avatar by using the classNames prop, each slot has its own className.

Data Attributes

Avatar has the following attributes on the base element:

• data-hover: When the avatar is being hovered. Based on useHover
• data-focus: When the avatar is being focused. Based on useFocusRing, it is applied when isFocusable is true or when the as property is assigned as button.
• data-focus-visible: When the avatar is being focused with the keyboard. Based on useFocusRing, it is applied when isFocusable is true or when the as property is assigned as button.

API

Avatar Props

Avatar Group Props