> To build a Wix site agentically, or add Wix features like bookings or a store to a site you already have, follow https://www.wix.com/headless/skill.md
> 
> Portal Navigation:
> 
> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
> - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages).
> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`).
> - If a reference page seems to be missing its schema (parameters, return types, or type definitions), append `?schema=true` to its `.md` URL (e.g. `https://dev.wix.com/docs/contexts/contexts/stores/category-info/use-category-info-context.md?schema=true`).
> - Top-level index of all portals: https://dev.wix.com/docs/llms.txt
> - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt

## Resource: Avatar Component

## Article: Avatar Component

## Article Link: https://dev.wix.com/docs/wix-design-system/components/media/avatar-component.md

## Article Content:

# Avatar

_Components/Media_

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

## Overview

```jsx
<Avatar presence="online" />;
```

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.

```jsx
<StorybookComponents.Stack>
  <Avatar shape="circle" />
  <Avatar shape="square" />
</StorybookComponents.Stack>;
```

#### 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.

```jsx
<StorybookComponents.Stack>
  <Avatar imgProps={{ src: 'AvatarExample4.jpg' }} />
  <Avatar imgProps={{ src: 'NotFoundImage.jpg' }} />
  <Avatar name="Anne Rikki" imgProps={{ src: 'NotFoundImage.jpg' }} />
</StorybookComponents.Stack>;
```

#### Size

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

```jsx
<StorybookComponents.Stack>
  <Avatar size="size90" name="Anne Rikki" />
  <Avatar size="size72" name="Anne Rikki" />
  <Avatar size="size60" name="Anne Rikki" />
  <Avatar size="size48" name="Anne Rikki" />
  <Avatar size="size36" name="Anne Rikki" />
  <Avatar size="size30" name="Anne Rikki" />
  <Avatar size="size24" name="Anne Rikki" />
  <Avatar size="size18" name="Anne Rikki" />
</StorybookComponents.Stack>;
```

#### Color

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

- `A1` blue
- `A2` arctic blue
- `A3` purple
- `A4` green
- `A5` magenta
- `A6` yellow

```jsx
<StorybookComponents.Stack>
  <Avatar color="A1" name="A 1" />
  <Avatar color="A2" name="A 2" />
  <Avatar color="A3" name="A 3" />
  <Avatar color="A4" name="A 4" />
  <Avatar color="A5" name="A 5" />
  <Avatar color="A6" name="A 6" />
</StorybookComponents.Stack>;
```

#### 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.

```jsx
<StorybookComponents.Stack>
  <Avatar presence="online" />
  <Avatar presence="offline" />
  <Avatar presence="busy" />
</StorybookComponents.Stack>;
```

#### 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.

```jsx
<StorybookComponents.Stack>
  <Avatar />
  <Avatar shape="square" />
  <Avatar
    shape="square"
    placeholder={
      <Box color="B20">
        <Icons.Toolbox />
      </Box>
    }
  />
</StorybookComponents.Stack>;
```

#### 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.

```jsx
() => {
  const CustomIndication = () => (
    <Box
      backgroundColor="D80"
      borderRadius={24}
      color="#4267B2"
      width="max-content"
    >
      <Icons.Facebook />
    </Box>
  );

  return (
    <StorybookComponents.Stack>
      <Avatar
        name="Anne Rikki"
        size="size90"
        customIndication={<CustomIndication />}
      />
      <Avatar
        name="Anne Rikki"
        size="size72"
        customIndication={<CustomIndication />}
      />
      <Avatar
        name="Anne Rikki"
        size="size60"
        customIndication={<CustomIndication />}
      />
      <Avatar
        name="Anne Rikki"
        size="size48"
        customIndication={<CustomIndication />}
      />
    </StorybookComponents.Stack>
  );
};
```

#### 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.

```jsx
<StorybookComponents.Stack>
  <Avatar name="Anne Rikki" size="size90" indication={<Icons.PhotoCamera />} />
  <Avatar name="Anne Rikki" size="size72" indication={<Icons.PhotoCamera />} />
  <Avatar name="Anne Rikki" size="size60" indication={<Icons.PhotoCamera />} />
  <Avatar name="Anne Rikki" size="size48" indication={<Icons.PhotoCamera />} />
</StorybookComponents.Stack>;
```

#### Show action on hover

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

```jsx
<StorybookComponents.Stack>
  <Avatar
    name="Anne Rikki"
    size="size90"
    indication={<Icons.PhotoCamera />}
    showIndicationOnHover
  />
  <Avatar
    name="Anne Rikki"
    size="size72"
    indication={<Icons.PhotoCamera />}
    showIndicationOnHover
  />
  <Avatar
    name="Anne Rikki"
    size="size60"
    indication={<Icons.PhotoCamera />}
    showIndicationOnHover
  />
  <Avatar
    name="Anne Rikki"
    size="size48"
    indication={<Icons.PhotoCamera />}
    showIndicationOnHover
  />
</StorybookComponents.Stack>;
```

#### 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.

```jsx
<StorybookComponents.Stack>
  <Avatar
    name="Anne Rikki"
    size="size90"
    indication={<Icons.PhotoCamera />}
    loading
  />
  <Avatar
    name="Anne Rikki"
    size="size72"
    indication={<Icons.PhotoCamera />}
    loading
  />
  <Avatar
    name="Anne Rikki"
    size="size60"
    indication={<Icons.PhotoCamera />}
    loading
  />
  <Avatar
    name="Anne Rikki"
    size="size48"
    indication={<Icons.PhotoCamera />}
    loading
  />
</StorybookComponents.Stack>;
```

### Common use case examples

#### Users list

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

```jsx
() => {
  const records = [
    {
      image: <Avatar size="size36" name="Sara Porter" />,
      name: 'Sara Porter',
      country: 'Canada',
      orders: 2,
      lastActivity: 'Sep 9, 2020',
    },
    {
      image: <Avatar size="size36" name="Michael Baldwin" />,
      name: 'Michael Baldwin',
      country: 'Germany',
      orders: 43,
      lastActivity: 'Sep 7, 2020',
    },
    {
      image: <Avatar size="size36" name="Alex Halifax" />,
      name: 'Alex Halifax',
      country: 'United Kingdom',
      orders: 12,
      lastActivity: 'Jun 30, 2020',
    },
    {
      image: <Avatar size="size36" name="Paul Sheffield" />,
      name: 'Paul Sheffield',
      country: 'US',
      orders: 0,
      lastActivity: 'Sep 18, 2019',
    },
  ];

  const columns = [
    { title: '', width: '36px', render: (row) => row.image },
    { title: 'Name', render: (row) => row.name },
    { title: 'Country', render: (row) => row.country },
    { title: 'Orders', render: (row) => row.orders },
    { title: 'Last Activity', render: (row) => row.lastActivity },
    {
      title: '',
      render: () => (
        <TableActionCell
          primaryAction={{
            text: 'Edit',
            onClick: () => {},
          }}
        />
      ),
    },
  ];

  return (
    <Card>
      <Table data={records} columns={columns}>
        <TableToolbar>
          <TableToolbar.Title>Customers</TableToolbar.Title>
        </TableToolbar>
        <Table.Content />
      </Table>
    </Card>
  );
};
```

#### Prefix

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

```jsx
<Dropdown
  placeholder="Select staff member"
  valueParser={(option) => option.value({ selected: option.id }).props.title}
  fixedFooter={<ListItemAction title="Add New Staff Member" />}
  options={[
    listItemSelectBuilder({
      id: 0,
      prefix: <Avatar size="size24" color="A1" name="Carmel Lloyd" />,
      title: 'Carmel Lloyd',
    }),
    listItemSelectBuilder({
      id: 1,
      prefix: <Avatar size="size24" color="A2" name="Gracie-May Marsden" />,
      title: 'Gracie-May Marsden',
    }),
    listItemSelectBuilder({
      id: 2,
      prefix: <Avatar size="size24" color="A3" name="Keisha Decker" />,
      title: 'Keisha Decker',
    }),
    listItemSelectBuilder({
      id: 3,
      prefix: <Avatar size="size24" color="A4" name="Ruairidh Fitzgerald" />,
      title: 'Ruairidh Fitzgerald',
    }),
    listItemSelectBuilder({
      id: 4,
      prefix: <Avatar size="size24" color="A5" name="Sheldon Chavez" />,
      title: 'Sheldon Chavez',
    }),
  ]}
/>;
```

#### Upload photo

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

```jsx
<Card>
  <Card.Content>
    <Layout gap="18px">
      <Cell>
        <Box verticalAlign="middle" align="space-between">
          <Box verticalAlign="middle">
            <FileUpload onChange={() => {}}>
              {({ openFileUploadDialog }) => (
                <Avatar
                  name="Anne Rikki"
                  size="size60"
                  onIndicationClick={openFileUploadDialog}
                  indication={<Icons.PhotoCamera size="24" />}
                />
              )}
            </FileUpload>
            <Box direction="vertical" padding="0 24px">
              <Heading size="large">Anne Rikki</Heading>
              <TextButton weight="normal" size="small">
                Edit Contact
              </TextButton>
            </Box>
          </Box>
          <Button>Send Message</Button>
        </Box>
      </Cell>
      <Cell>
        <Divider />
      </Cell>
      <Cell>
        <Box gap="60px">
          <Box direction="vertical">
            <Text size="tiny" secondary light>
              Email
            </Text>
            <Text size="small">anne.rikki@email.com</Text>
          </Box>
          <Box direction="vertical">
            <Text size="tiny" secondary light>
              Phone
            </Text>
            <Text size="small">+44 734 349973</Text>
          </Box>
          <Box direction="vertical">
            <Text size="tiny" secondary light>
              Billing Address
            </Text>
            <Text size="small">2549 Perine Street, Vermont</Text>
          </Box>
        </Box>
      </Cell>
    </Layout>
  </Card.Content>
</Card>;
```

## Code

```jsx
import { Avatar } from '@wix/design-system';
```

### Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `ariaLabel` | `string` | — | 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. |
| `customIndication` | `ReactNode` | — | 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). |
| `dataHook` | `string` | — | Applies a data-hook HTML attribute that can be used in the tests. |
| `imgProps` | `ImgHTMLAttributes<HTMLImageElement>` | — | Accept all common `<img>` tag properties. |
| `indication` | `ReactNode` | — | Accept any content to render as an indication item. |
| `loading` | `boolean` | — | Shows a loader on top of an avatar. |
| `name` | `string` | — | 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. |
| `placeholder` | `ReactNode` | — | Accept any content to render as a content placeholder. This placeholder is displayed if no text, name or imgProps are provided.<br> 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. |
| `showIndicationOnHover` | `boolean` | `false` | Shows indication element on hover. |
| `size` | `"size90" \| "size72" \| "size60" \| "size48" \| "size36" \| "size30" \| "size24" \| "size18"` | `'size48'` | Controls the size of an avatar. |
| `text` | `string` | — | Defines a text to render as a content instead of a given `name`. |
| `title` | `string` | — | Defines a standard HTML title attribute value. Applies it to the root element. |

## Testkit

Import the driver matching your test environment:

```jsx
// UniDriver
import { AvatarUniDriver } from '@wix/design-system/dist/testkit/unidriver';

// Vanilla
import { AvatarTestkit } from '@wix/design-system/dist/testkit';

// Puppeteer
import { AvatarTestkit } from '@wix/design-system/dist/testkit/puppeteer';

// Testing Library
import { AvatarTestkit } from '@wix/design-system/dist/testkit/testing-library';
```

### Driver methods

| Method | Description |
| --- | --- |
| `click` | Clicks on the Avatar element |
| `getContentType` | Gets the content type |
| `getTextContent` | Gets the text content |
| `isImageLoaded` | Checks whether the image is loaded |
| `hover` | Hovers the component |
| `indicationExists` | Checks whether the Avatar indication exists |
| `clickIndication` | Clicks the Avatar indication |
| `customIndicationExists` | Checks whether the Avatar custom indication exists |
| `clickCustomIndication` | Clicks the Avatar custom indication |
| `isLoading` | Checks whether the Avatar is loading |
| `exists` | Checks whether the component found with the given data hook. |
| `element` | Gets the component root element. |
| `base` | Returns 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](invalid-url)) — has visual changes
- **1.299.0** (2026-07-17) — breaking: update accent colors and the user illustration ([#16568](invalid-url)) — 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](invalid-url)) — 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](invalid-url))
- **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