useAvatar

Usage#

import { useAvatar } from '@primereact/headless/avatar';
import { useAvatarGroup } from '@primereact/headless/avatargroup';

const { rootProps, state, handleImageLoad, handleImageUnload } = useAvatar();
 
return <div {...rootProps}></div>;

useAvatar owns the image-loading lifecycle and exposes state.load for fallback rendering, while useAvatarGroup returns root props for grouping multiple avatars. See Primitive for a component-based API.

Features#

• Image loading lifecycle — attaches load/error listeners and flips state.load so you can swap between image and fallback
• Imperative load helpers — handleImageLoad(src) starts a preload and handleImageUnload() cleans listeners up
• Delayed reveal — delayDuration holds the image hidden for a short window to avoid layout flashes on fast connections
• Group layout primitive — useAvatarGroup exposes a root prop object with shared data attributes so child avatars can be styled relative to each other
• Data-attribute styling — scoped data-scope / data-part attributes on both avatar and group roots

Working with callbacks#

Preload an image with cleanup#

Trigger the preload in an effect and unload on teardown so event listeners never leak.

const { state, handleImageLoad, handleImageUnload } = useAvatar();
 
React.useEffect(() => {
    handleImageLoad('https://example.com/photo.png');
    return () => handleImageUnload();
}, []);

Render a fallback until the image resolves#

Use state.load to decide between the real image and initials, an icon, or a placeholder.

<div {...rootProps}>{state.load ? <img src="https://example.com/photo.png" alt="User" /> : <span>AB</span>}</div>

Avoid flash on fast networks#

Set delayDuration so the loaded image only appears after the given delay, which keeps the UI stable when images resolve almost instantly.

const avatar = useAvatar({ delayDuration: 300 });

Group avatars with shared styling#

Wrap a set of avatars in an element spread with useAvatarGroup's rootProps to share layout data attributes.

const { rootProps: groupRootProps } = useAvatarGroup();
 
<div {...groupRootProps}>{/* multiple avatar elements */}</div>;

Styling with data attributes#

Every prop object includes data-scope and data-part attributes you can target directly from CSS.

[data-scope='avatar'][data-part='root'] {
    width: 3rem;
    height: 3rem;
    border-radius: 50%;
    overflow: hidden;
}
 
[data-scope='avatargroup'][data-part='root'] {
    display: flex;
    align-items: center;
}
 
[data-scope='avatargroup'][data-part='root'] > [data-scope='avatar'] {
    margin-left: -0.75rem;
}

API#

useAvatar#

useAvatarGroup#

Accessibility#

Static visual element — use aria-label for screen reader descriptions. See Primitive for full WAI-ARIA compliance details.