> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cognite.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Cognite Data Fusion (CDF) is an industrial DataOps platform. Prefer English docs unless the user asks for another locale.
> Follow /_llms/ index links recursively until you reach page URLs ending in .md. Fetch those Markdown twins instead of HTML.
> For REST APIs, default to calendar version 20230101 (stable). Use 20230101-beta or 20230101-alpha only if the user is on a preview API. Cite paths under /api-reference/concepts/<version>/ and the Cdf-Version header. Prefer the Python SDK (cognite-sdk) unless the user is in JavaScript/TypeScript.
> Start here by task: platform overview /cdf/index.md; data modeling /cdf/dm/index.md; data integration /cdf/integration/index.md; access /cdf/access/index.md; CDF Toolkit /cdf/deploy/cdf_toolkit/index.md; REST quickstart /dev/quickstart.md; Python SDK /dev/sdks/python/index.md; Atlas AI /cdf/atlas_ai/concepts/index.md; Flows apps /cdf/flows/index.md; Aura UI /cdf/aura/index.md; MCP and IDE setup /dev/guides/ide_ai_integration.md.
> For implementation work, also load /skill.md.

# Avatar

> An Avatar is a graphical representation of a user or concept. It is typically used to personalize user interfaces by displaying profile pictures, initials, or icons and help users quickly recognize individuals in collaborative environments.

<Badge color="blue">v1.0.0</Badge> | [View in Storybook](https://master--695bb4b1b8041ae09768950a.chromatic.com/?path=/docs/primitives-avatar--docs)

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-avatar--basic" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-avatar--basic&viewMode=story&globals=theme:light" title="Avatar basic story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>

## When to use

* Representing a user profile in collaboration features such as messaging, sharing, or comments.
* Providing a visual cue for accounts, teams, or organizations in collaborative interfaces.
* Signaling concepts or features such as an agent avatar.

## When to use something else

* **Decorative visuals for onboarding or [Empty states](/cdf/aura/primitives/empty-state):** Use an illustration asset or icon instead of an Avatar.

## Dos and don'ts

* **Do** size Avatars based on the context they are used in, i.e. use a Small Avatar when paired next to a Small [Button](/cdf/aura/primitives/button).
* **Do** randomize colors when using the icon or initial icon types.
* **Do** mix image types with icon or initial types as needed.
* **Don't** rely only on Avatars when a name is more useful for the context.

## Behavior

* When space limits, use an overflow avatar with a dropdown Menu to indicate there are more users hidden.
* Avatars can be view-only or interactive, depending on the context.
* Avatars can display badge dots to indicate status or online presence.

## Often used with

[Badge](/cdf/aura/primitives/badge) (status dot), [Tooltip](/cdf/aura/primitives/tooltip) (name or details), [Menu](/cdf/aura/primitives/dropdown-menu) for "+N" overflow stacks in collaborator lists.

## Accessibility

* Image alt text: Provide descriptive alt text (e.g., `alt="Sarah Connor"`) when the avatar stands alone. Use `alt=""` and `aria-hidden="true"` if accompanied by visible adjacent text labels.
* Fallback accessibility: Render plain text fallback initials inside the DOM with verified 4.5:1 contrast against the background container when images fail to load.

## Visual examples

The examples below are interactive and follow the doc site's theming: light mode when the docs site is in light mode, and dark mode when you switch the docs site to dark mode.

### With icon

Use an Avatar with an icon when representing a non-person entity such as a team, service, or concept—for example, an AI agent or application.

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-avatar--with-icon" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-avatar--with-icon&viewMode=story&globals=theme:light" title="Avatar with icon story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>

### With image

Use an Avatar with a profile image when a user's photo is available to help collaborators quickly recognize individuals in lists, comments, or assignment UI.

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-avatar--with-image" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-avatar--with-image&viewMode=story&globals=theme:light" title="Avatar with image story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>

### All colorways

Choose an Avatar colorway to differentiate users or entities when no image is available; assign colors randomly but keep them consistent in the same session.

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-avatar--all-colorways" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-avatar--all-colorways&viewMode=story&globals=theme:light" title="Avatar all colorways story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>

### All sizes

Select an Avatar size based on context—smaller in dense lists and tables, larger in profile headers or detail views—to maintain visual hierarchy and legibility.

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-avatar--all-sizes" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-avatar--all-sizes&viewMode=story&globals=theme:light" title="Avatar all sizes story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>

### Avatar group spacing

Use Avatar group spacing to display multiple collaborators with consistent overlap and alignment, making it clear how many people are involved without consuming excessive horizontal space.

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-avatar--avatar-group-spacing" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-avatar--avatar-group-spacing&viewMode=story&globals=theme:light" title="Avatar avatar group spacing story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>

### Overflow avatar with menu

Use an overflow Avatar with a menu when more collaborators exist than can be displayed inline; the overflow control reveals the full list on interaction.

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-avatar--overflow-avatar-with-menu" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-avatar--overflow-avatar-with-menu&viewMode=story&globals=theme:light" title="Avatar overflow avatar with menu story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>

### Click interaction

Make an Avatar clickable when selecting or viewing a user profile is a primary action—for example, opening a collaborator's details from a comment thread or clicking to follow a collaborator in a canvas environment.

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-avatar--click-interaction" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-avatar--click-interaction&viewMode=story&globals=theme:light" title="Avatar click interaction story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>