# Avatar (/cloud/primitives/avatar)
```ts title="Import"
import { Avatar, AvatarFallback, AvatarImage } from "@nyte-ai/ui";
```
Implemented in `packages/ui/src/components/ui/avatar.tsx`, wrapping `@base-ui/react/avatar`
(no dedicated headless subpath; the styled wrapper is the only export).
## Usage [#usage]
* Always include `AvatarFallback`. The image can fail, and the fallback is what a screen reader
user and a slow network both get.
* Fallback text is two characters. The font sizes are tuned for that and nothing longer fits at
`xs`.
* `tone` is for identity (a participant, an agent), not for status. Do not use `green` to mean
online.
* `AvatarImage` needs `alt`. If the avatar is decorative beside the participant's name, `alt=""`.
## Anatomy [#anatomy]
```tsx
```
`Avatar` renders a `` with `data-slot="avatar"`, `data-size`, and `data-tone`. Image and
fallback set `data-slot="avatar-image"` and `data-slot="avatar-fallback"`.
## Examples [#examples]
### Sizes and shapes [#sizes-and-shapes]
```tsx
IL
NY
SM
XS
```
### Tones [#tones]
## Props [#props]
### Avatar [#avatar]
| Prop | Type | Default | Description |
| ------------------------------ | -------------------------------------------------------- | ----------- | -------------------------------------------- |
| `size` | `"xs" \| "sm" \| "md" \| "lg"` | `"md"` | 20, 24, 28, or 36px. |
| `shape` | `"circle" \| "rounded"` | `"circle"` | Pill radius or `--nyte-radius-avatar` (42%). |
| `tone` | `"neutral" \| "orange" \| "blue" \| "violet" \| "green"` | `"neutral"` | Background and foreground pair. |
| `className`, `style`, `xstyle` | see [Theming](/cloud/foundations/theming) | | |
Displays a user's profile picture, initials, or fallback icon.
Renders a `` element.
**Root Props:**
| Prop | Type | Default | Description |
| :-------- | :---------------------------------------------------------------------------------------- | :------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| className | `string \| ((state: Avatar.Root.State) => string \| undefined)` | - | CSS class applied to the element, or a function that
returns a class based on the component's state. |
| style | `React.CSSProperties \| ((state: Avatar.Root.State) => React.CSSProperties \| undefined)` | - | Style applied to the element, or a function that
returns a style object based on the component's state. |
| render | `ReactElement \| ((props: HTMLProps, state: Avatar.Root.State) => ReactElement)` | - | Allows you to replace the component's HTML element
with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |
### AvatarImage [#avatarimage]
The image to be displayed in the avatar.
Renders an `![]()
` element.
**Image Props:**
| Prop | Type | Default | Description |
| :-------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------- | :------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| onLoadingStatusChange | `((status: ImageLoadingStatus) => void)` | - | Callback fired when the loading status changes. |
| className | `string \| ((state: Avatar.Image.State) => string \| undefined)` | - | CSS class applied to the element, or a function that
returns a class based on the component's state. |
| style | `React.CSSProperties \| ((state: Avatar.Image.State) => React.CSSProperties \| undefined)` | - | Style applied to the element, or a function that
returns a style object based on the component's state. |
| keepMounted | `boolean` | `false` | Whether the image element stays mounted and loads in place instead of being preloaded.
Supports `loading="lazy"` and optimized image components such as `next/image`. |
| render | `ReactElement \| ((props: React.DetailedHTMLProps, HTMLImageElement>, state: Avatar.Image.State) => ReactElement)` | - | Allows you to replace the component's HTML element
with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |
**Image Data Attributes:**
| Attribute | Type | Description |
| :------------------ | :--- | :------------------------------------------ |
| data-error | - | Present when the image failed to load. |
| data-loading | - | Present while the image is loading. |
| data-starting-style | - | Present when the image begins animating in. |
| data-ending-style | - | Present when the image is animating out. |
### AvatarFallback [#avatarfallback]
Rendered when the image fails to load or when no image is provided.
Renders a `` element.
**Fallback Props:**
| Prop | Type | Default | Description |
| :-------- | :-------------------------------------------------------------------------------------------- | :------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| delay | `number` | `0` | How long to wait before showing the fallback. Specified in milliseconds. |
| className | `string \| ((state: Avatar.Fallback.State) => string \| undefined)` | - | CSS class applied to the element, or a function that
returns a class based on the component's state. |
| style | `React.CSSProperties \| ((state: Avatar.Fallback.State) => React.CSSProperties \| undefined)` | - | Style applied to the element, or a function that
returns a style object based on the component's state. |
| render | `ReactElement \| ((props: HTMLProps, state: Avatar.Fallback.State) => ReactElement)` | - | Allows you to replace the component's HTML element
with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |
## Accessibility [#accessibility]
* The root is a ``; it has no role. Meaning comes from the image's `alt` or from the text
around it.
* Base UI tracks image loading status and swaps to the fallback on error or while loading;
`delay` on the fallback avoids a flash for fast loads.
## Styling [#styling]
| Token | Role |
| -------------------------------------------------- | ------------------------------------- |
| `--nyte-avatar-size-*`, `--nyte-avatar-font-*` | Per-size box and fallback font |
| `--nyte-avatar-ring-width` | 0.5px border in `--nyte-color-border` |
| `--nyte-color-avatar-*-background` / `-foreground` | Per-tone pair |
| `--nyte-radius-avatar`, `--nyte-radius-pill` | Shapes |
| `--nyte-font-weight-semibold` | Fallback weight |