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

AttributeTypeDescriptionDefault
srcstringThe source URL of the image to be displayed.-
colordefault | primary | secondary | success | warning | dangerSets the avatar background color.default
radiusnone | sm | md | lg | fullSets the avatar border radius.full
sizesm | md | lgSets the avatar size.md
namestringDisplays the initials if the image is not provided or fails to load.-
iconReactNodeDisplays a custom icon inside the avatar.-
fallbackReactNodeA custom fallback component to display when the image fails to load.-
isBorderedbooleanIf true, adds a border around the avatar.false
isDisabledbooleanIf true, disables the avatar and applies a disabled styling.false
isFocusablebooleanIf true, makes the avatar focusable for keyboard navigation.false
showFallbackbooleanIf true, shows the fallback icon or initials when the image fails to load.false
ImgComponentReact.ElementTypeThe component to be used as the image element.img
imgPropsImgComponentPropsProps to be passed to the image element.-
classNamesRecord<"base"| "img"| "fallback"| "name"| "icon", string>Allows to set custom class names for the avatar slots.-

Avatar Group Props

AttributeTypeDescriptionDefault
maxnumberThe maximum number of visible avatars5
totalnumberControl the number of avatar not visible-
sizeAvatarProps['size']Size of the avatars-
colorAvatarProps['color']Color of the avatars-
radiusAvatarProps['radius']Radius of the avatars-
isGridbooleanWhether the avatars should be displayed in a gridfalse
isDisabledbooleanWhether the avatars are disabled-
isBorderedbooleanWhether the avatars have a border-
renderCount(count: number) => ReactNodeThis allows you to render a custom count component.-
classNamesRecord<"base"| "count", string>Allows to set custom class names for the avatar group slots.-