Chakra Docs


⦾ The Avatar component in Chakra UI is a versatile and feature-rich tool designed for representing user profiles, contributors, or any other form of user identity in a visual format. It's a great addition to applications where identifying users or participants visually is important, such as in chat apps, social media platforms, collaborative tools, or even in comment sections of a blog.

The Avatar component's primary function is to display an image that typically represents a user's profile picture. However, the Avatar component goes beyond merely displaying an image; it provides several features and options for customization:

  • Fallback Support: If an image fails to load or isn't provided, the Avatar component can automatically display the user's initials instead. This is achieved by passing the user's name to the name prop of the Avatar component.
  • Size Adjustments: Chakra UI allows you to adjust the size of the avatar to better fit your interface design. This can be done by passing predefined values like "xs", "sm", "md", "lg", "xl", "2xl", etc., to the size prop.
  • Shape Customization: The shape of the Avatar can be customized by modifying the borderRadius prop. While avatars are typically round, you can set it to a square, or any other shape that CSS border-radius supports.
  • Border Customization: You can add a border to the Avatar by using borderColor and borderWidth props. This is useful in situations where you want the Avatar to stand out from the background.
  • Grouping Avatars: Chakra UI also provides an AvatarGroup component which allows you to display a stack of avatars, useful for showing multiple users or contributors. This component can also show the excess number of avatars if they exceed the limit set.
  • Badges: The Chakra UI Avatar component can also be combined with the Badge component to display statuses like "online", "offline", "do not disturb", etc.
  • Custom Default Avatar: In scenarios where you don't want to fall back to initials, Chakra UI also allows you to set a custom default avatar that will be used when the src prop is falsy.

The flexibility, ease of use, and the built-in fallback and accessibility features of the Avatar component makes it a go-to choice for developers who need a reliable and customizable way to display user profiles in their applications. It allows for a wide range of creative implementations while ensuring a great and consistent user experience.

The three avatar-related components described below work together to give developers a flexible and powerful way to represent users within their applications. The Avatar represents the user, the AvatarBadge provides additional status information, and the AvatarGroup allows for showing multiple users together, each serving their own unique purpose, yet working harmoniously together. With the right combination, they can significantly enhance the visual representation of users in your application.

  • Avatar: As previously mentioned, the Avatar component is primarily used to display an image that represents the user. It accepts several props which allow for extensive customization of appearance and behavior. Key properties include src for the image source, name for the textual representation (used for generating initials in case of an image failure), size for defining the size of the avatar, borderRadius to change the shape, and borderColor and borderWidth to customize the border.

    Additionally, you can apply any style props that Chakra UI provides, giving you more freedom to customize the look and feel of the Avatar to match your application's design system. This includes properties for color, spacing, typography, and more. Additionally, the Avatar component supports all standard HTML attributes and event handlers.

  • AvatarBadge: The AvatarBadge is a sub-component that allows you to add supplementary visual information to your Avatar. This badge is a small circular element that overlays the Avatar, typically placed at the bottom-right corner. It's commonly used to indicate a user's status, like online, offline, busy, and more.

    You can customize the appearance of the AvatarBadge using Chakra UI's style props, and it's often colored to indicate the status. For instance, green for online, red for busy, and gray for offline. The boxSize prop can be used to adjust the size of the badge. It's as simple as nesting the AvatarBadge component within the Avatar component in your JSX code.

  • AvatarGroup:The AvatarGroup component is a handy wrapper that lets you display multiple Avatar components together in a stack. This is particularly useful when you want to show several users, such as a group chat or a list of contributors to a project.

    The AvatarGroup component uses the spacing prop to adjust the distance between the stacked Avatars. When the number of Avatars exceeds a set limit, it can automatically show an excess indicator, which is a "+" sign followed by the number of extra Avatars not shown. This limit can be set with the max prop.

These components can be imported as follows:


Basic Avatar Implementation

⦾ Our first example illustrates a basic use case of the Avatar component, creating a row of six avatars, each with their respective images. If an image fails to load, the component falls back to showing the initials of the person's name. This approach is commonly used in chat interfaces, contact lists, or anywhere you need to display a list of users or contributors.


Sizing for Avatars

⦾ In Chakra UI, the Avatar component supports various pre-defined sizes including "xs" (extra small), "sm" (small), "md" (medium), "lg" (large), "xl" (extra large), and "2xl" (double extra large). You can set the size by passing one of these values to the size prop of the Avatar component, allowing you to easily control the dimensions of the avatar images in your application. There are six avatars in this layout, each representing a different person and assigned a unique size from "xs" to "2xl".


Fallback for Avatar Loading Errors

⦾ The Avatar component in Chakra UI provides flexible and robust fallback mechanisms for situations where an avatar image fails to load. The following is a demonstration that showcases these fallback mechanisms, as well as customization of the fallback avatar. This level of customization make the Avatar component an excellent choice for handling user avatars in your application.

In this example, we have an Avatar component for three different people, each with a different size and a broken link for the src prop, hence the images will not load. This provides us with an opportunity to explore the fallbacks provided by the Avatar component.

The first two avatars have a name prop, which the Avatar component uses to generate initials to display in the absence of an image. Additionally this, the bg prop is used to customize the background color of the fallback avatar. The icon prop is used to display a custom icon (from the react-icons library in this case) in place of the initials.

For the third avatar, we don't provide a name prop. In this case, Chakra UI will use the custom icon and background color specified by the icon and bg props as the fallback avatar.


Using Avatar Badges

⦾ Avatar badges are incredibly useful for indicating additional information such as the online status of a user. They are placed in the corner of the avatar image and can be fully customized to fit the design of your application.

In this example, we have a row of three Avatar components, each representing a different person with a respective image provided by the src prop. Nested within each Avatar component is an AvatarBadge. The boxSize prop is used to determine the size of each badge relative to the avatar's font size. For the first avatar, the badge has a green background, indicating that the user is online.

For the second and third avatars, we not only change the background color of the badge using the bg prop but also specify a border color using the borderColor prop. These badges could signify different statuses - for example, the "deeppink" badge could indicate a 'busy' status, and a yellow one could denote 'away' status.

By using these props, we can manipulate the appearance of each badge to suit our design needs, providing a clear and efficient way to visually communicate additional information to our users.

It's important to highlight that the em unit is used for sizing the AvatarBadge. This approach is beneficial because it allows the badge's size to adjust proportionally to the avatar's font size.


Displaying an Avatar Group

⦾ When you need to display a group of users or a team, you can use Chakra UI's AvatarGroup component. It allows you to neatly stack multiple Avatar components together. You can limit the number of visible avatars and adjust their size and spacing.

In this example, we have an AvatarGroup component that contains five individual Avatar components. The size prop in AvatarGroup applies to all Avatars, making them 'large'. The max prop limits the number of visible avatars to three. Avatars beyond this limit are not shown individually but are represented by a "+2" badge. The spacing prop is used to set the degree of overlap between the avatars, providing a compact, visually appealing user group display.

This functionality is useful, for instance, in a chat application where you may want to show a preview of the group's members, or in a project management tool where you would want to display the project's team members.



Modifying the Initials Logic

⦾ The getInitials prop is introduced to give developers control over how the initials are derived from the name. By default, the logic combines the first characters of each word in the name prop.

In this example, we've replaced the default initials logic with a new function that generates initials in reverse order. So, for 'Person One', the Avatar component will display 'OP' instead of the default 'PO'.

Remember, the getInitials prop accepts a function that takes the full name as an argument and returns the initials string. This means you can implement any initials logic that fits your specific needs.


Did you know?

Creative Idea No. 1

Avatars as Buttons: While not an obvious use case, you can wrap the Avatar component in a button or link to create a clickable avatar. This is useful in cases where you want users to click on an avatar, perhaps to view a user's profile or start a chat.


Creative Idea No. 2

Gradient Background Avatars: The Avatar component's bg prop doesn't only accept solid colors. You can also pass in gradient values to create a more vibrant and dynamic avatar, especially when no image is provided. This can help make your interface more colorful and engaging.


Creative Idea No. 3

Custom Shapes: Although avatars are usually round, you can change their shape by manipulating the borderRadius prop. If you want to distinguish certain avatars or just prefer a different style, this can be a unique way to customize the appearance of your avatars.


copyright © 2023 IHeartComponents |


Special thanks to Stefan Bohacek / Generative Placeholders.