# Avatar

Represent one person or group with an image or text, plus optional presence and activity indicators. Use AvatarGroup for multiple avatars.

## Behavior and states

- Avatars can include presence badges to indicate the status of an associated person.
- Avatars can include activity rings to indicate when a person is currently collaborating in a shared activity.
- By default, avatars are static elements that don’t have states built in.
- If you include additional interactions to provide more context or information, be sure to author in states and keyboarding interactions.

## Default

Source: CoreAI.

[Download source](/coreai-design-system/source/examples/components-avatar--default.tsx)

```tsx
// Copyright (c) Microsoft Corporation.
// Licensed under the MIT license.

import type { JSXElement } from "@coreai-ds/react-components";
import { Avatar } from "@coreai-ds/react-components";
import * as React from 'react';

// `Avatar` is the CoreAI-wrapped avatar — it extends Fluent's `color` prop
// with an additional `"neutral-alt"` value.
// ---------- Default (canonical Fluent story) ----------
export const Default = (): JSXElement => <Avatar aria-label="Guest"/>;

export default Default;
```

## API

Generated CoreAI prop summaries, not replacement type declarations. Most native DOM/event and ARIA props are omitted. `?` means optional; JSDoc shows defaults, deprecations, and conditional requirements. Defaults assume the standard CoreAI provider.

### Avatar API

```ts
interface AvatarProps {
  /**
   * Optional activity indicator
   * * active: the avatar will be decorated according to activeAppearance
   * * inactive: the avatar will be reduced in size and partially transparent
   * * unset: normal display
   * @default unset
   */
  active?: "active" | "inactive" | "unset";

  /**
   * The appearance when `active="active"`
   * @default ring
   */
  activeAppearance?: "ring" | "shadow" | "ring-shadow";

  as?: "span";

  /**
   * Badge to show the avatar's presence status.
   */
  badge?: WithSlotShorthandValue<Omit<ComponentProps<Pick<BadgeSlots, "root" | "icon">>, "color"> & Pick<BadgeProps, "size"> & { status?: PresenceBadgeStatus; outOfOffice?: boolean; } & RefAttributes<HTMLDivElement>> | null | undefined;

  children?: any;

  className?: string;

  /**
   * The color of the avatar. In addition to Fluent's options, CoreAI adds
   * `"neutral-alt"` so a neutral avatar can sit on either a low- or
   * high-elevation surface with appropriate contrast.
   *
   * - `"neutral"` uses `colorNeutralBackground4`
   * - `"neutral-alt"` uses `colorNeutralBackground1`
   */
  color?: "anchor" | "brand" | "neutral" | "colorful" | "dark-red" | "cranberry" | "red" | "pumpkin" | "peach" | "marigold" | "gold" | "brass" | "brown" | "forest" | "seafoam" | "dark-green" | "light-teal" | "teal" | "steel" | "blue" | "royal-blue" | "cornflower" | "navy" | "lavender" | "purple" | "grape" | "lilac" | "pink" | "magenta" | "plum" | "beige" | "mink" | "platinum" | "neutral-alt";

  /**
   * Icon to be displayed when the avatar doesn't have an image or initials.
   * @default `PersonRegular` (the default icon's size depends on the Avatar's size)
   */
  icon?: WithSlotShorthandValue<{ as?: "span"; } & Omit<Omit<DetailedHTMLProps<HTMLAttributes<HTMLSpanElement>, HTMLSpanElement>, "ref"> & { ref?: ((instance: HTMLSpanElement | null) => void) | RefObject<HTMLSpanElement> | null; }, "children"> & { children?: any; }> | null | undefined;

  /**
   * Specify a string to be used instead of the name, to determine which color to use when color="colorful".
   * Use this when a name is not available, but there is another unique identifier that can be used instead.
   */
  idForColor?: string;

  /**
   * The Avatar's image.
   *
   * Usage e.g.: `image={{ src: '...' }}`
   */
  image?: ({ as?: "img"; } & Omit<Omit<DetailedHTMLProps<ImgHTMLAttributes<HTMLImageElement>, HTMLImageElement>, "ref"> & { ref?: ((instance: HTMLImageElement | null) => void) | RefObject<HTMLImageElement> | null; }, "children"> & { children?: undefined; }) | null | undefined;

  /**
   * (optional) Custom initials.
   *
   * It is usually not necessary to specify custom initials; by default they will be derived from the `name` prop,
   * using the `getInitials` function.
   *
   * The initials are displayed when there is no image (including while the image is loading).
   */
  initials?: WithSlotShorthandValue<{ as?: "span"; } & Omit<Omit<DetailedHTMLProps<HTMLAttributes<HTMLSpanElement>, HTMLSpanElement>, "ref"> & { ref?: ((instance: HTMLSpanElement | null) => void) | RefObject<HTMLSpanElement> | null; }, "children"> & { children?: any; }> | null | undefined;

  /**
   * The name of the person or entity represented by this Avatar. This should always be provided if it is available.
   *
   * The name is used to determine the initials displayed when there is no image. It is also provided to
   * accessibility tools.
   */
  name?: string;

  ref?: Ref<HTMLSpanElement>;

  /**
   * The avatar can have a circular or square shape.
   * @default circular
   */
  shape?: "circular" | "square";

  /**
   * Size of the avatar in pixels.
   *
   * Size is restricted to a limited set of supported values recommended for most uses (see `AvatarSizeValue`) and
   * based on design guidelines for the Avatar control.
   *
   * Note: At size 16, if initials are displayed, only the first initial will be rendered.
   *
   * If a non-supported size is needed, set `size` to the next-smaller supported size, and set `width` and `height`
   * to override the rendered size.
   *
   * For example, to set the avatar to 45px in size:
   * `<Avatar size={40} style={{ width: '45px', height: '45px' }} />`
   * @default 32
   */
  size?: 16 | 20 | 24 | 28 | 32 | 36 | 40 | 48 | 56 | 64 | 72 | 96 | 120 | 128;

  style?: CSSProperties;
}
```

## Implementation

CoreAI 0.12.0; Fluent 9.74.9.

[Setup and dependencies](/coreai-design-system/guides/Package.md).

Import components from `@coreai-ds/react-components`. CoreAI guidance above takes precedence over API demonstration examples.

Note: Storybook-only layout decorators are omitted. Examples use the documentation preview spacing instead.

## Active

Source: Fluent, adapted for CoreAI.

An avatar can communicate whether a user is currently active (for example, speaking or typing). Avatar supports `active`, `inactive`, and `unset`. The default is `unset`.

[Download source](/coreai-design-system/source/examples/components-avatar--active.tsx)

```tsx
// Copyright (c) Microsoft Corporation.
// Licensed under the MIT license.

import type { JSXElement } from "@coreai-ds/react-components";
import { Avatar } from "@coreai-ds/react-components";
import * as React from 'react';

export const Active = (): JSXElement => (<div style={{ display: 'flex', gap: '20px' }}>
    <Avatar active="active" name="Ashley McCarthy"/>
    <Avatar active="inactive" name="Isaac Fielder" badge={{ status: 'away' }}/>
  </div>);

export default Active;
```

## Active Appearance

Source: Fluent, adapted for CoreAI.

An avatar can have different appearances when `active="active"`. Avatar supports `ring`, `shadow`, and `ring-shadow`. The default is `ring`.

[Download source](/coreai-design-system/source/examples/components-avatar--active-appearance.tsx)

```tsx
// Copyright (c) Microsoft Corporation.
// Licensed under the MIT license.

import type { JSXElement } from "@coreai-ds/react-components";
import { Avatar } from "@coreai-ds/react-components";
import * as React from 'react';

export const ActiveAppearance = (): JSXElement => (<div style={{ display: 'flex', gap: '20px' }}>
    <Avatar active="active" activeAppearance="ring" name="Ring"/>
    <Avatar active="active" activeAppearance="shadow" name="Shadow"/>
    <Avatar active="active" activeAppearance="ring-shadow" name="Ring Shadow"/>
  </div>);

export default ActiveAppearance;
```

## Badge

Source: Fluent, adapted for CoreAI.

An avatar can have a badge to indicate presence status. See the PresenceBadge component for more info.

[Download source](/coreai-design-system/source/examples/components-avatar--badge.tsx)

```tsx
// Copyright (c) Microsoft Corporation.
// Licensed under the MIT license.

import type { JSXElement } from "@coreai-ds/react-components";
import { Avatar } from "@coreai-ds/react-components";
import * as React from 'react';

export const Badge = (): JSXElement => (<>
    <Avatar name="Lydia Bauer" badge={{ status: 'available' }}/>
    <Avatar name="Amanda Brady" badge={{ status: 'busy' }}/>
    <Avatar name="Henry Brill" badge={{ status: 'out-of-office' }}/>
    <Avatar name="Robin Counts" badge={{ status: 'away' }}/>
    <Avatar name="Tim Deboer" badge={{ status: 'offline' }}/>
    <Avatar name="Cameron Evans" badge={{ status: 'do-not-disturb' }}/>
    <Avatar name="Wanda Howard" badge={{ status: 'blocked' }}/>
    <Avatar name="Mona Kane" badge={{ status: 'available', outOfOffice: true }}/>
    <Avatar name="Allan Munger" badge={{ status: 'busy', outOfOffice: true }}/>
    <Avatar name="Erik Nason" badge={{ status: 'out-of-office', outOfOffice: true }}/>
    <Avatar name="Daisy Phillips" badge={{ status: 'away', outOfOffice: true }}/>
    <Avatar name="Kevin Sturgis" badge={{ status: 'offline', outOfOffice: true }}/>
    <Avatar name="Elliot Woodward" badge={{ status: 'do-not-disturb', outOfOffice: true }}/>
    <Avatar name="Wanda Howard" badge={{ status: 'blocked', outOfOffice: true }}/>
  </>);

export default Badge;
```

## Badge Icon

Source: Fluent, adapted for CoreAI.

An Avatar can have a custom icon inside the badge.

[Download source](/coreai-design-system/source/examples/components-avatar--badge-icon.tsx)

```tsx
// Copyright (c) Microsoft Corporation.
// Licensed under the MIT license.

import type { JSXElement } from "@coreai-ds/react-components";
import { Avatar } from "@coreai-ds/react-components";
import { CalendarMonthRegular } from "@fluentui/react-icons";
import * as React from 'react';

export const BadgeIcon = (): JSXElement => <Avatar name="John Doe" badge={{ icon: <CalendarMonthRegular /> }}/>;

export default BadgeIcon;
```

## Color: brand

Source: Fluent, adapted for CoreAI.

An avatar can use the brand color from the theme's palette.

[Download source](/coreai-design-system/source/examples/components-avatar--color-brand.tsx)

```tsx
// Copyright (c) Microsoft Corporation.
// Licensed under the MIT license.

import type { JSXElement } from "@coreai-ds/react-components";
import { Avatar } from "@coreai-ds/react-components";
import * as React from 'react';

export const ColorBrand = (): JSXElement => <Avatar color="brand" initials="BR" name="brand color avatar"/>;

export default ColorBrand;
```

## Color: colorful

Source: Fluent, adapted for CoreAI.

An avatar can have the color be automatically picked based on the `name` prop (or `idForColor` can be used if a name is not available).

[Download source](/coreai-design-system/source/examples/components-avatar--color-colorful.tsx)

```tsx
// Copyright (c) Microsoft Corporation.
// Licensed under the MIT license.

import type { JSXElement } from "@coreai-ds/react-components";
import { Avatar } from "@coreai-ds/react-components";
import { GuestRegular } from "@fluentui/react-icons";
import * as React from 'react';

export const ColorColorful = (): JSXElement => (<>
    <Avatar color="colorful" name="Katri Athokas"/>
    <Avatar color="colorful" name="Elvia Atkins"/>
    <Avatar color="colorful" name="Cameron Evans"/>
    <Avatar color="colorful" name="Wanda Howard"/>
    <Avatar color="colorful" name="Mona Kane"/>
    <Avatar color="colorful" name="Allan Munger"/>
    <Avatar color="colorful" name="Daisy Phillips"/>
    <Avatar color="colorful" name="Robert Tolbert"/>
    <Avatar color="colorful" name="Kevin Sturgis"/>
    <Avatar color="colorful" name="Elliot Woodward"/>
    <Avatar color="colorful" idForColor="id-123" icon={<GuestRegular />} aria-label="Guest"/>
    <Avatar color="colorful" idForColor="42" icon={<GuestRegular />} aria-label="Guest"/>
    <Avatar color="colorful" idForColor="93" icon={<GuestRegular />} aria-label="Guest"/>
    <Avatar color="colorful" idForColor="Guest-23" icon={<GuestRegular />} aria-label="Guest"/>
  </>);

export default ColorColorful;
```

## Color Neutral

Source: CoreAI.

[Download source](/coreai-design-system/source/examples/components-avatar--color-neutral.tsx)

```tsx
// Copyright (c) Microsoft Corporation.
// Licensed under the MIT license.

import type { JSXElement } from "@coreai-ds/react-components";
import { Avatar } from "@coreai-ds/react-components";
import * as React from 'react';

export const ColorNeutral = (): JSXElement => {
    const styles = /* css */ `
      .avatar-example {
        display: flex;
        column-gap: var(--spacingHorizontalXXL);
      }

      .avatar-example__surface {
        display: flex;
        flex-direction: column;
        align-items: center;
        row-gap: var(--spacingVerticalS);
        padding: var(--spacingVerticalXXL);
        border-radius: var(--borderRadiusMedium);
      }

      .avatar-example__surface--background-4 {
        background-color: var(--colorNeutralBackground4);
      }

      .avatar-example__surface--background-1 {
        background-color: var(--colorNeutralBackground1);
      }

      .avatar-example__label {
        font-size: var(--fontSizeBase200);
        color: var(--colorNeutralForeground2);
      }
    `;
    return (<>
      <style>{styles}</style>
      <div className="avatar-example">
        <div className="avatar-example__surface avatar-example__surface--background-1">
          <Avatar name="Alex Britez" color="neutral"/>
          <span className="avatar-example__label">color="neutral" (colorNeutralBackground4)</span>
        </div>
        <div className="avatar-example__surface avatar-example__surface--background-4">
          <Avatar name="Alex Britez" color="neutral-alt"/>
          <span className="avatar-example__label">
            color="neutral-alt" (colorNeutralBackground1)
          </span>
        </div>
      </div>
    </>);
};

export default ColorNeutral;
```

## Color: named color

Source: Fluent, adapted for CoreAI.

An avatar can have a specific named color from the theme's color palette  (e.g. `seafoam`, `grape`, or `pumpkin`)

[Download source](/coreai-design-system/source/examples/components-avatar--color-palette.tsx)

```tsx
// Copyright (c) Microsoft Corporation.
// Licensed under the MIT license.

import type { JSXElement } from "@coreai-ds/react-components";
import { Avatar } from "@coreai-ds/react-components";
import * as React from 'react';

export const ColorPalette = (): JSXElement => (<>
    <Avatar initials="DR" color="dark-red" name="darkRed avatar"/>
    <Avatar initials="CR" color="cranberry" name="cranberry avatar"/>
    <Avatar initials="RE" color="red" name="red avatar"/>
    <Avatar initials="PU" color="pumpkin" name="pumpkin avatar"/>
    <Avatar initials="PE" color="peach" name="peach avatar"/>
    <Avatar initials="MA" color="marigold" name="marigold avatar"/>
    <Avatar initials="GO" color="gold" name="gold avatar"/>
    <Avatar initials="BS" color="brass" name="brass avatar"/>
    <Avatar initials="BR" color="brown" name="brown avatar"/>
    <Avatar initials="FO" color="forest" name="forest avatar"/>
    <Avatar initials="SE" color="seafoam" name="seafoam avatar"/>
    <Avatar initials="DG" color="dark-green" name="darkGreen avatar"/>
    <Avatar initials="LT" color="light-teal" name="lightTeal avatar"/>
    <Avatar initials="TE" color="teal" name="teal avatar"/>
    <Avatar initials="ST" color="steel" name="steel avatar"/>
    <Avatar initials="BL" color="blue" name="blue avatar"/>
    <Avatar initials="RB" color="royal-blue" name="royalBlue avatar"/>
    <Avatar initials="CO" color="cornflower" name="cornflower avatar"/>
    <Avatar initials="NA" color="navy" name="navy avatar"/>
    <Avatar initials="LA" color="lavender" name="lavender avatar"/>
    <Avatar initials="PU" color="purple" name="purple avatar"/>
    <Avatar initials="GR" color="grape" name="grape avatar"/>
    <Avatar initials="LI" color="lilac" name="lilac avatar"/>
    <Avatar initials="PI" color="pink" name="pink avatar"/>
    <Avatar initials="MA" color="magenta" name="magenta avatar"/>
    <Avatar initials="PL" color="plum" name="plum avatar"/>
    <Avatar initials="BE" color="beige" name="beige avatar"/>
    <Avatar initials="MI" color="mink" name="mink avatar"/>
    <Avatar initials="PL" color="platinum" name="platinum avatar"/>
    <Avatar initials="AN" color="anchor" name="anchor avatar"/>
  </>);

export default ColorPalette;
```

## Icon

Source: Fluent, adapted for CoreAI.

An avatar can display an icon. The icon will only be shown when there is no image or initials available.

[Download source](/coreai-design-system/source/examples/components-avatar--icon.tsx)

```tsx
// Copyright (c) Microsoft Corporation.
// Licensed under the MIT license.

import type { JSXElement } from "@coreai-ds/react-components";
import { Avatar } from "@coreai-ds/react-components";
import { GuestRegular } from "@fluentui/react-icons";
import { PeopleRegular } from "@fluentui/react-icons";
import { PeopleTeamRegular } from "@fluentui/react-icons";
import { PersonCallRegular } from "@fluentui/react-icons";
import { CalendarLtrRegular } from "@fluentui/react-icons";
import { BriefcaseRegular } from "@fluentui/react-icons";
import { ConferenceRoomRegular } from "@fluentui/react-icons";
import * as React from 'react';

export const Icon = (): JSXElement => (<>
    <Avatar icon={<GuestRegular />} aria-label="Guest"/>
    <Avatar icon={<PeopleRegular />} aria-label="Group"/>
    <Avatar icon={<PeopleTeamRegular />} shape="square" aria-label="Team"/>
    <Avatar icon={<PersonCallRegular />} aria-label="Phone Contact"/>
    <Avatar icon={<CalendarLtrRegular />} aria-label="Meeting"/>
    <Avatar icon={<BriefcaseRegular />} shape="square" aria-label="Tenant"/>
    <Avatar icon={<ConferenceRoomRegular />} shape="square" aria-label="Room"/>
  </>);

export default Icon;
```

## Image

Source: Fluent, adapted for CoreAI.

An avatar can display an image.<br/>It is recommended to also include a name in addition to the image: the initials from the name are displayed while the image is loading, and the name makes the Avatar accessible to screen readers.

[Download source](/coreai-design-system/source/examples/components-avatar--image.tsx)

```tsx
// Copyright (c) Microsoft Corporation.
// Licensed under the MIT license.

import type { JSXElement } from "@coreai-ds/react-components";
import { Avatar } from "@coreai-ds/react-components";
import * as React from 'react';

export const Image = (): JSXElement => (<Avatar name="Katri Athokas" image={{ src: 'https://fabricweb.azureedge.net/fabric-website/assets/images/avatar/KatriAthokas.jpg' }}/>);

export default Image;
```

## Initials: Custom Initials

Source: Fluent, adapted for CoreAI.

An avatar can display custom initials by setting the initials prop. It is generally recommended to use
        the `name` prop instead, as that will automatically determine the initials and display them.

[Download source](/coreai-design-system/source/examples/components-avatar--initials.tsx)

```tsx
// Copyright (c) Microsoft Corporation.
// Licensed under the MIT license.

import type { JSXElement } from "@coreai-ds/react-components";
import { Avatar } from "@coreai-ds/react-components";
import * as React from 'react';

export const Initials = (): JSXElement => <Avatar name="Cecil Robin Folk" initials="CRF"/>;

export default Initials;
```

## Name

Source: Fluent, adapted for CoreAI.

The name is used to determine the initials displayed by the Avatar. It is also read by screen readers.

[Download source](/coreai-design-system/source/examples/components-avatar--name.tsx)

```tsx
// Copyright (c) Microsoft Corporation.
// Licensed under the MIT license.

import type { JSXElement } from "@coreai-ds/react-components";
import { Avatar } from "@coreai-ds/react-components";
import * as React from 'react';

export const Name = (): JSXElement => <Avatar name="Ashley McCarthy"/>;

export default Name;
```

## Size

Source: Fluent, adapted for CoreAI.

An avatar supports a range of sizes from 16 to 128. The default is 32. 

Avoid using sizes 16 and 20 for interactive Avatars, or ensure that there is at least 8px or 4px spacing respectively to meet WCAG target size requirements.

[Download source](/coreai-design-system/source/examples/components-avatar--size.tsx)

```tsx
// Copyright (c) Microsoft Corporation.
// Licensed under the MIT license.

import type { JSXElement } from "@coreai-ds/react-components";
import { Avatar } from "@coreai-ds/react-components";
import * as React from 'react';

export const Size = (): JSXElement => (<>
    <Avatar initials="16" size={16}/>
    <Avatar initials="20" size={20}/>
    <Avatar initials="24" size={24}/>
    <Avatar initials="28" size={28}/>
    <Avatar initials="32" size={32}/>
    <Avatar initials="36" size={36}/>
    <Avatar initials="40" size={40}/>
    <Avatar initials="48" size={48}/>
    <Avatar initials="56" size={56}/>
    <Avatar initials="64" size={64}/>
    <Avatar initials="72" size={72}/>
    <Avatar initials="96" size={96}/>
    <Avatar initials="120" size={120}/>
    <Avatar initials="128" size={128}/>
  </>);

export default Size;
```

## Shape: square

Source: Fluent, adapted for CoreAI.

An avatar can have a square shape.

[Download source](/coreai-design-system/source/examples/components-avatar--square.tsx)

```tsx
// Copyright (c) Microsoft Corporation.
// Licensed under the MIT license.

import type { JSXElement } from "@coreai-ds/react-components";
import { Avatar } from "@coreai-ds/react-components";
import { PeopleTeamRegular } from "@fluentui/react-icons";
import * as React from 'react';

export const Square = (): JSXElement => (<Avatar shape="square" aria-label="square avatar" icon={<PeopleTeamRegular />}/>);

export default Square;
```

## Resources

- [Figma component](https://www.figma.com/design/eXfSQrRg3poHRgmr0ivN5V/CoreAI-Figma-Library?node-id=306874-117056)
- [Fluent guidance](https://fluent2.microsoft.design/components/web/react/core/avatar/usage)