Avatar

Components/Media

Interactive docs page: https://wix-pages.com/design-system-documentation/#/component/avatar

Overview

Copy

Avatar visually represents a user or an organization either as an image, text (name initials) or a placeholder image.

Do

  • Use it in circle shape to represent a user.
  • Use it in square shape to represent an organization.

Don't

  • Don't use it to display visual content other than users or organizations. Use <Image/> instead.
  • Don't use it to display a group of users. Use <AvatarGroup/> instead.
  • Don't use it as a round image placeholder, use <Image/> instead.

Feature examples

Shape

Control the form of the avatar with a shape prop. It supports 2 shapes:
 - `circle` (default) - use it to represent a user.
 - `square` - use it to represent an entity such as a company or organization.

Copy

Content states

Component has 3 states:
 - Loads image when image URL is provided.
 - Falls back to the placeholder when provided image URL is broken or not given.
 - Display initials when image URL is broken or not given, but avatar name is defined.

Copy

Size

Adjust the avatar size using size prop. It supports 8 sizes:
 - `size90`
 - `size72`
 - `size60`
 - `size48` (default)
 - `size36`
 - `size30`
 - `size24`
 - `size18`

Copy

Color

Control avatar color with color prop. It supports 6 colors:

  • A1 blue
  • A2 arctic blue
  • A3 purple
  • A4 green
  • A5 magenta
  • A6 yellow
Copy

Presence

Use the presence prop to indicate the status of a user. It supports 3 statuses:
 - `online` - indicates that user is online.
 - `offline` - indicates that user is not available.
 - `busy` - indicates that user is online, but is busy, so might not be accessible.

Copy

Placeholder

Display a placeholder when component has no image and no name. When required, override default placeholders to any custom elements by passing required content to `placeholder` prop.

Copy

Indication

Render any indicator via `customIndication` prop. It accepts any component or a set of them within a restricted dimensions:
 - 30x30px container for avatar in `size90`, `size72`.
 - 24x24px container for avatar in `size60`, `size48`.
Smaller avatar sizes cannot have custom indicators.

Copy

Action button

Render related action such as image upload as an icon button with `indication` prop. This prop applies for 4 largest avatar sizes only: size90, size72, size60 and size48.

Copy

Show action on hover

Reveal action button on avatar hover only with `showIndicationOnHover` prop.

Copy

Loader

Render related action such as image upload as an icon button with `indication` prop. This prop applies for 4 largest avatar sizes only: size90, size72, size60 and size48.

Copy

Common use case examples

Users list

Use <Avatar/> as a first data column in a table to visually represent your customers.

Copy

Prefix

Use <Avatar/> as a prefix item to build user selections.

Copy

Upload photo

Use an `indication` prop to display a button allowing users to manually upload a photo to avatar

Copy

Code

Copy

Props

NameTypeDefaultDescription
ariaLabelstring—Defines a string that labels the current element in case where text label isn't visible on the screen.
color"A1" | "A2" | "A3" | "A4" | "A5" | "A6" | "A7"—Controls the background color of the avatar. If not provided, color is determined by the provided text or name so that each name receives a different color.
customIndicationReactNode—Accept any content to render as a custom indication item. This indication element won't be wrapped by an IconButton. It could be rendered in other shapes (such as square).
dataHookstring—Applies a data-hook HTML attribute that can be used in the tests.
imgPropsImgHTMLAttributes<HTMLImageElement>—Accept all common <img> tag properties.
indicationReactNode—Accept any content to render as an indication item.
loadingboolean—Shows a loader on top of an avatar.
namestring—Defines a name of the avatar user. Text initials are generated from the name. The name value is used as the default value for HTML title and aria-label attributes. And also as default value for the image's alt attribute if imgProps is provided.
onClick() => void—Defines a click event handler. When defined, component will be clickable and will have a pointer cursor on hover.
onIndicationClick() => void—Defines a callback function which is called every time indication element is clicked.
placeholderReactNode—Accept any content to render as a content placeholder. This placeholder is displayed if no text, name or imgProps are provided.
By default use a generic avatar user icon.
presence"online" | "offline" | "busy"—Sets the presence status of an avatar.
shape"circle" | "square"'circle'Controls the shape of the image.
showIndicationOnHoverbooleanfalseShows indication element on hover.
size"size90" | "size72" | "size60" | "size48" | "size36" | "size30" | "size24" | "size18"'size48'Controls the size of an avatar.
textstring—Defines a text to render as a content instead of a given name.
titlestring—Defines a standard HTML title attribute value. Applies it to the root element.

Testkit

Import the driver matching your test environment:

Copy

Driver methods

MethodDescription
clickClicks on the Avatar element
getContentTypeGets the content type
getTextContentGets the text content
isImageLoadedChecks whether the image is loaded
hoverHovers the component
indicationExistsChecks whether the Avatar indication exists
clickIndicationClicks the Avatar indication
customIndicationExistsChecks whether the Avatar custom indication exists
clickCustomIndicationClicks the Avatar custom indication
isLoadingChecks whether the Avatar is loading
existsChecks whether the component found with the given data hook.
elementGets the component root element.
baseReturns UniDriver for the base element.

Changelog

  • 1.340.0 (2026-10-21) — maintenance release, no component-specific changes
  • 1.339.0 (2026-10-19) — maintenance release, no component-specific changes
  • 1.338.0 (2026-10-15) — maintenance release, no component-specific changes
  • 1.330.3 (2026-09-29) — maintenance release, no component-specific changes
  • 1.329.0 (2026-09-24) — maintenance release, no component-specific changes
  • 1.325.0 (2026-09-17) — maintenance release, no component-specific changes
  • 1.323.0 (2026-09-10) — maintenance release, no component-specific changes
  • 1.320.0 (2026-09-03) — maintenance release, no component-specific changes
  • 1.310.0 (2026-08-10) — maintenance release, no component-specific changes
  • 1.305.0 (2026-07-28) — breaking: add seventh color to rotation and 20px tiny size [Harmony, Studio 2.0] (#16637) — has visual changes
  • 1.299.0 (2026-07-17) — breaking: update accent colors and the user illustration (#16568) — has visual changes
  • 1.295.0 (2026-07-03) — maintenance release, no component-specific changes
  • 1.294.0 (2026-07-02) — fix: reveal indication on mobile (#16456) — has visual changes
  • 1.292.0 (2026-06-22) — maintenance release, no component-specific changes
  • 1.291.0 (2026-06-19) — maintenance release, no component-specific changes
  • 1.271.0 (2026-04-22) — maintenance release, no component-specific changes
  • 1.266.0 (2026-04-07) — maintenance release, no component-specific changes
  • 1.260.0 (2026-03-17) — maintenance release, no component-specific changes
  • 1.247.2 (2026-01-21) — maintenance release, no component-specific changes
  • 1.241.0 (2025-12-17) — maintenance release, no component-specific changes
  • 1.212.0 (2025-08-11) — maintenance release, no component-specific changes
  • 1.165.0 (2025-02-27) — maintenance release, no component-specific changes
  • 1.156.0 (2025-01-29) — feat: add color property (#14477)
  • 1.154.0 (2025-01-17) — maintenance release, no component-specific changes
  • 1.138.1 (2024-10-30) — maintenance release, no component-specific changes
  • 1.102.0 (2024-04-16) — maintenance release, no component-specific changes
  • 1.92.1 (2024-02-05) — maintenance release, no component-specific changes

Last updated: 22 October 2026

Did this help?