Free and open-source React avatar components built for modern applications and websites. These avatars are built using React Aria and styled with Tailwind CSS.
Olivia Rhye
olivia@untitledui.com
Installation
You can add this avatar component using our CLI or manually:
npx untitledui@latest add avatar
Avatar examples
Below are examples and variations of this avatar component:
Border
Use the border boolean prop to add an outer border around the avatar, helping it stand out against busy or low-contrast backgrounds.
Status indicator
Status indicators are a common way to show the online or offline status of a user or connection. They can be used to indicate whether a user is online or offline.
Our avatar component provides a status prop that allows you to easily add status indicators to your avatars. The status prop accepts the following values: online and offline.
Company logo
Company logos or avatar badges are another way to add additional information to your avatars. They can be used to display the company logo, the user's role, or any other information you want to display.
Our avatar component provides a badge prop that allows you to easily add company logos to your avatars. The badge prop accepts a React node and will be displayed in the top-right corner of the avatar. We recommend using the AvatarCompanyIcon component to easily add a company logo with predefined styles and sizes to your avatars.
Verified badge
Verified badges are quite common in any modern application. They indicate whether a user is verified and trustworthy.
Our avatar component provides a verified boolean prop that allows you to easily add styled verified badges to your avatars.
Placeholder
Avatar components should be built with common edge cases in mind. For example, what should happen if a user has no avatar, or if the provided image has failed to load?
Our avatar components are designed to be robust and handle common edge cases. For example, if no image is provided, or if the image fails to load, the component will automatically display a placeholder icon.
To change the placeholder, you can use the placeholder and placeholderIcon props. You can pass an icon (e.g., any icon from @untitledui/icons) to the placeholderIcon prop, and it will be displayed in the center of the avatar with matching styles. If you would like something more custom, you can also pass a React node to the placeholder prop.
Initials
Similar to the placeholder, you can also use the initials prop to display the user's initials when no image is available.
Label group
Avatar label groups are a great way to display additional information about a user. They can be used to display the user's name, email, and any other information you want to display.
Olivia Rhye
olivia@untitledui.com
Olivia Rhye
olivia@untitledui.com
Olivia Rhye
olivia@untitledui.com
Group
Group avatars are also quite common in modern applications. They can be used to display a group of users or entities that belong to the same group.
To build a group of avatars, you can easily use our Avatar and AvatarAddButton components. Just place them in a flex container with appropriate spacing and you're good to go.
Profile photo placeholder
Profile photo placeholders function the same way as the regular placeholder in our Avatar component. They will be displayed if no image is provided, or if the image fails to load.
Profile photo initials
Profile photo initials function the same way as the regular initials in our Avatar component. They will be displayed if no image is provided, or if the image fails to load.
API reference
Avatar
Import Avatar from @/components/base/avatar/avatar. Renders a <div> element.
AvatarLabelGroup
Import AvatarLabelGroup from @/components/base/avatar/avatar-label-group. Renders a <figure> element.
AvatarProfilePhoto
Import AvatarProfilePhoto from @/components/base/avatar/avatar-profile-photo. Renders a <div> element.
FAQs
Please refer to our frequently asked questions page for more.
If src is empty or the image fails to load, Avatar falls back in this order: initials, then the placeholderIcon component, then the placeholder element, and finally a default User01 icon.
Set status to "online" or "offline". It renders a dot in the bottom-right corner, green for "online" and neutral gray for "offline", sized to match the avatar.
Yes. Use verified for a verified tick, count for a number badge, or badge for any element such as a company logo. Only one indicator renders at a time, picked in the order status, verified, count, badge, so setting status hides the other three.
Avatar accepts a size of "xs", "sm", "md", "lg", "xl" or "2xl", defaulting to "md". AvatarLabelGroup and AvatarProfilePhoto only accept "sm", "md" and "lg", and both type size as required.
Pass rounded={false}. The avatar then uses small rounded corners instead of a full circle.
Place the avatars in a flex -space-x-2 container and give each one className="ring-[1.5px] ring-bg-primary" so they separate visually, as the group example does. To end the stack with an add button, use AvatarAddButton from @/components/base/avatar/base-components, which takes a required size of "xs", "sm" or "md" and a title (default "Add user") used for its tooltip and aria-label.
Set focusable on the Avatar and add the group class to the link around it. The ring is styled with group-focus-visible, so it only appears when that parent receives keyboard focus.