> ## Documentation Index
> Fetch the complete documentation index at: https://docs.twenty.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Avatar
> Represent a person or record with an image, initial, or icon.
export const StoryEmbed = ({storyId, title, height = 120}) => <>
Open in Storybook
;
`Avatar` shows an image with a first-letter fallback. Use it beside a record name or inside a [Chip](/ui/primitives/data-display/chip). Its default root is a presentational `span`.
## Usage
```tsx theme={null}
import { Avatar } from 'twenty-ui/primitives/data-display';
export const WorkspaceAvatar = () => (
);
```
When the image is absent or fails to load, the fallback shows the first letter of the trimmed name in uppercase. An empty name shows `-`. `colorSeed` chooses stable fallback colors and defaults to `name`; use a record identifier to keep the color stable when the name changes.
The image and default fallback are decorative. `name` supplies the visual initial and fallback colors without adding an accessible label. When the avatar is the only representation of a person or record, set `imageProps={{ alt: name }}` to label both the image and default fallback. Keep the avatar decorative when a visible name or labeled owner already provides that information.
`imageProps` accepts the complete image contract, including `srcSet`, `sizes`, `crossOrigin`, `referrerPolicy`, native events, refs, and `render`. Its `src` overrides the shorthand `src`. `fallbackProps` accepts the complete fallback contract, including `delay`, children, labeling, refs, and `render`. A custom fallback `render` owns its accessibility semantics; set `aria-hidden` explicitly when it is decorative.
```tsx theme={null}
import { Avatar } from 'twenty-ui/primitives/data-display';
type RecordAvatarProps = {
name: string;
imageUrl?: string;
initials: string;
};
export const RecordAvatar = ({
name,
imageUrl,
initials,
}: RecordAvatarProps) => (
);
```
## Compose the parts
Use `Avatar.Root`, `Avatar.Image`, and `Avatar.Fallback` when you own the anatomy. Root supplies the size, shape, and fallback appearance; it does not generate children or accessible labels.
```tsx theme={null}
import { Avatar } from 'twenty-ui/primitives/data-display';
type ContactAvatarProps = {
name: string;
imageUrl?: string;
initials: string;
};
export const ContactAvatar = ({
name,
imageUrl,
initials,
}: ContactAvatarProps) => (
{initials}
);
```
The parts share Base UI's image loading state. Image renders an `img` after a successful load by default, and Fallback renders a `span` while the image is absent, loading, or has failed. `delay` postpones the initial fallback display in milliseconds and defaults to `0`. A changed source is loaded again and can replace either the current image or fallback.
`Avatar.Image` exposes `onLoadingStatusChange` with `idle`, `loading`, `loaded`, and `error` status values. The callback runs when Base UI reports a non-idle status change; unmounting the Image part resets the shared root state to `idle`. Root, Image, and Fallback accept state-aware `className`, `style`, and `render` functions with `imageLoadingStatus`; Image also exposes `transitionStatus`.
Use `keepMounted` on Image when the rendered image must load in place, including `loading="lazy"` or an optimized image component. Forward native attributes, events, and the ref from custom image renderers. A mounted image can still be loading or failed; inspect loading state rather than treating its presence as success.
The front component renderer currently supports the default preload path with `src`. Its host image does not receive `srcSet`, `sizes`, `loading`, `decoding`, or `referrerPolicy`. A changing custom `render` function with `keepMounted` can leave a decoded image hidden because the worker cannot read its completion state or dimensions. Use default preloading there until those renderer capabilities are available.
The public `AvatarRootProps`, `AvatarImageProps`, `AvatarFallbackProps`, `AvatarRootState`, `AvatarImageState`, `AvatarFallbackState`, and `AvatarImageLoadingStatus` types are exported from `twenty-ui/primitives/data-display`. Refs target the rendered DOM element: `span`, `img`, and `span` by default, or the element supplied through `render`.
## Shape and appearance
`shape` accepts `square`, `rounded-square`, or `circle`. Sizes run from `xs` (12px) to `xl` (40px); `md` is 16px. `variant="outline"` adds a border to the fallback. The `color`, `backgroundColor`, and `borderColor` overrides customize the fallback, while a loaded image keeps its original appearance.
```tsx theme={null}
import { IconUser } from 'twenty-ui/icon';
import { Avatar } from 'twenty-ui/primitives/data-display';
export const ContactIcon = () => (
}
shape="rounded-square"
size="xl"
role="img"
aria-label="Contact"
/>
);
```
An `icon` takes precedence over both the image and the first-letter fallback. The icon itself is decorative, so label the root when it conveys information. `pulsing` animates opacity and respects reduced-motion preferences.
## Open a profile
```tsx theme={null}
import { Avatar } from 'twenty-ui/primitives/data-display';
type ProfileAvatarProps = {
onOpenProfile: () => void;
disabled?: boolean;
};
export const ProfileAvatar = ({
onOpenProfile,
disabled = false,
}: ProfileAvatarProps) => (
}
/>
);
```
Compose a native button for actions. It owns focus, Enter and Space activation, and disabled behavior. Supply an action-specific accessible name. Put `onClick` and `disabled` on the rendered button; shorthand Avatar has no `onClick`, `disabled`, or `nativeButton` prop.
For navigation, compose an anchor with an `href` or a router link that preserves anchor semantics. Native links activate with Enter. Keep navigation and disabled behavior with the link or interactive component you compose.
```tsx theme={null}
import { Avatar } from 'twenty-ui/primitives/data-display';
export const ProfileLink = () => (
}
/>
);
```
## Migrate clickable avatars
Compose a native button through `render` for actions, or an anchor or router link for navigation. Move `onClick` and `disabled` onto that owner and remove `nativeButton`. Give the owner a useful accessible name and avoid nesting interactive elements. `Avatar.Root` and the other explicit parts retain the complete Base UI event contract.
Shorthand avatars are decorative by default. `name` does not name the image, fallback, or interactive owner. Use a nonempty `imageProps.alt` only when the avatar conveys identity that is not already supplied by visible text or an owner label. With explicit parts, supply image alternative text and fallback labels or decorative attributes yourself, and keep translated content in your application.
## Props
Types and defaults are generated from the public component types. The explicit parts accept native attributes and event handlers. Shorthand Avatar omits `onClick`; supply it on the owner passed through `render`.
Background color override for a first-letter fallback.
Border color override for the outline fallback.
CSS class applied to the element, or a function that
returns a class based on the component's state.
Text color override for a first-letter fallback.
Stable value used to choose fallback colors. Defaults to `name`.
Complete `Avatar.Fallback` props, including caller-owned children, labeling, refs, `render`, and fallback `delay` in milliseconds.
Decorative icon rendered instead of the image and first-letter fallback. Give the root an accessible label when the icon conveys information.
Complete `Avatar.Image` props, including native image attributes, refs, `render`, `keepMounted`, and `onLoadingStatusChange`. Alternative text defaults to an empty string. Supply a nonempty `alt` to label the image and default fallback.
Name used for the first-letter fallback and fallback colors. Does not add an accessible label.
Animates the avatar opacity. Respects reduced-motion preferences.
Caller-supplied root element or renderer. Defaults to a presentational span. Compose a native button or link explicitly for interaction, and put its click handler and disabled state on that owner.
Surrounds the avatar with a background-colored ring so overlapping avatars stay distinct.
Shape of the avatar and its fallback.
Avatar size: `xs` (12px), `sm` (14px), `md` (16px), `lg` (24px), or `xl` (40px).
Image URL. A missing or failed image shows the fallback. `imageProps.src` overrides this value.
Style applied to the element, or a function that
returns a style object based on the component's state.
Visual treatment of the fallback.
### Avatar.Root
Background color override for a first-letter fallback.
Border color override for the outline fallback.
Caller-owned Image, Fallback, and other content.
CSS class applied to the element, or a function that
returns a class based on the component's state.
Text color override for a first-letter fallback.
Stable value used to choose fallback colors. Defaults to `name`.
Name used to choose fallback colors. Does not add children or accessible labels.
Animates the avatar opacity. Respects reduced-motion preferences.
Caller-supplied root element or renderer. Defaults to a presentational span. Compose a native button or link explicitly for interaction, and put its click handler and disabled state on that owner.
Surrounds the avatar with a background-colored ring so overlapping avatars stay distinct.
Shape of the avatar and its fallback.
Avatar size: `xs` (12px), `sm` (14px), `md` (16px), `lg` (24px), or `xl` (40px).
Style applied to the element, or a function that
returns a style object based on the component's state.
Visual treatment of the fallback.
### Avatar.Image
Caller-owned alternative text. Use an empty string for decorative images.
CSS class applied to the element, or a function that
returns a class based on the component's state.
Native image cross-origin policy, also used during preloading.
Keeps the image mounted and loads it in place. Loading and failed images stay hidden while Fallback is shown.
Native eager or lazy loading. Use keepMounted for lazy loading.
Called when Base UI reports a loading, loaded, or error status. Shares that state with Root and Fallback.
Native image referrer policy, also used during preloading.
Replaces the image. Preserve a native image and forward the supplied attributes, events, and ref.
Native responsive image sizes used with srcSet.
Image URL. Image renders after a successful load unless keepMounted is enabled.
Native responsive image source candidates.
Style applied to the element, or a function that
returns a style object based on the component's state.
### Avatar.Fallback
Caller-owned fallback content, such as initials or an icon.
CSS class applied to the element, or a function that
returns a class based on the component's state.
Milliseconds before the initial fallback is shown. Defaults to 0.
Replaces the fallback span. Forward the supplied props and ref, and provide its accessible label or decorative attributes.
Style applied to the element, or a function that
returns a style object based on the component's state.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.