Avatar

An unstyled avatar component with compound composition and group support.

Build fully custom avatar elements with complete control over layout and styling.

basic-demo

Pre-styled Versions

Choose a pre-styled library to use Avatar with ready-made designs.

Styled

Theme-based styling with CSS variables

Tailwind

Utility-first styling with Tailwind CSS

For hook-based usage without components, see the Headless API.

Features#

Compound component API with three sub-components: Root, Image, Fallback
AvatarGroup for visually grouping multiple avatars
Automatic image load detection — Image renders only after successful load, Fallback renders otherwise
Configurable delayDuration for delayed image reveal

Usage#

import { Avatar } from 'primereact/avatar';
import { AvatarGroup } from 'primereact/avatargroup';

<AvatarGroup>
    <Avatar.Root>
        <Avatar.Image src="..." />
        <Avatar.Fallback></Avatar.Fallback>
    </Avatar.Root>
</AvatarGroup>

Behavior#

Polymorphic Rendering#

Use as on any sub-component to change the rendered HTML element.

<Avatar.Root as="span">
    <Avatar.Image src="..." />
    <Avatar.Fallback as="div">AB</Avatar.Fallback>
</Avatar.Root>

Default elements: Root=div, Image=img, Fallback=span.

Render Function Children#

Avatar.Fallback accepts a render function as children, providing access to the component instance.

<Avatar.Fallback>{(instance) => <span>{instance.avatar?.state.load ? 'Loaded' : 'Fallback'}</span>}</Avatar.Fallback>

Pass Through#

Some parts may not be visible in the preview depending on the component's current state.

/* Select a part to see its CSS selector for custom styling */

API#

AvatarRoot#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: AvatarRootInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: AvatarRootInstance) => string)`	—
The class name to apply to the component.
`as`	`string` \| `number` \| `bigint` \| `boolean` \| `ComponentClass<any, any>` \| `FunctionComponent<any>` \| `ReactElement<unknown, string` \| `JSXElementConstructor<any>>` \| `Iterable<ReactNode, any, any>` \| `ReactPortal` \| `Promise<AwaitedReactNode>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`AvatarRootInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<AvatarRootPassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: AvatarRootInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`delayDuration`	`number`	—
The delay duration of the avatar.
`size`	`"large"` \| `"normal"` \| `"xlarge"`	`normal`
Defines the size of the avatar.
`shape`	`"circle"` \| `"square"`	`square`
Defines the shape of the avatar.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Attribute	Value
`data-scope`	`"avatar"`
`data-part`	`"root"`

Defines passthrough(pt) options of AvatarRoot component.

label	type	description
root	AvatarRootPassThroughType<HTMLAttributes<HTMLDivElement>>	Used to pass attributes to the root's DOM element.
fallback	AvatarRootPassThroughType<HTMLAttributes<HTMLSpanElement>>	Used to pass attributes to the fallback's DOM element.
image	AvatarRootPassThroughType<ImgHTMLAttributes<HTMLImageElement>>	Used to pass attributes to the image's DOM element.

AvatarImage#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: AvatarImageInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: AvatarImageInstance) => string)`	—
The class name to apply to the component.
`as`	`ReactNode`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`AvatarImageInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<AvatarImagePassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: AvatarImageInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`src`	`string`	`undefined`
Specifies the path to the image to display.
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Defines passthrough(pt) options of AvatarImage component.

label	type	description
root	AvatarImagePassThroughType<ImgHTMLAttributes<HTMLImageElement>>	Used to pass attributes to the root's DOM element.

AvatarFallback#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: AvatarFallbackInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: AvatarFallbackInstance) => string)`	—
The class name to apply to the component.
`as`	`string` \| `number` \| `bigint` \| `boolean` \| `ComponentClass<any, any>` \| `FunctionComponent<any>` \| `ReactElement<unknown, string` \| `JSXElementConstructor<any>>` \| `Iterable<ReactNode, any, any>` \| `ReactPortal` \| `Promise<AwaitedReactNode>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`AvatarFallbackInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<AvatarFallbackPassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: AvatarFallbackInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Defines passthrough(pt) options of AvatarFallback component.

label	type	description
root	AvatarFallbackPassThroughType<HTMLAttributes<HTMLSpanElement>>	Used to pass attributes to the root's DOM element.

AvatarGroup#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: AvatarGroupInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: AvatarGroupInstance) => string)`	—
The class name to apply to the component.
`as`	`string` \| `number` \| `bigint` \| `boolean` \| `ComponentClass<any, any>` \| `FunctionComponent<any>` \| `ReactElement<unknown, string` \| `JSXElementConstructor<any>>` \| `Iterable<ReactNode, any, any>` \| `ReactPortal` \| `Promise<AwaitedReactNode>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`AvatarGroupInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<AvatarGroupPassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: AvatarGroupInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Attribute	Value
`data-scope`	`"avatargroup"`
`data-part`	`"root"`

Defines passthrough(pt) options of AvatarGroup component.

label	type	description
root	AvatarGroupPassThroughType<HTMLAttributes<HTMLDivElement>>	Used to pass attributes to the root's DOM element.

Accessibility#

Avatar does not include any roles and attributes by default. Any attribute is passed to the root element so a role like img along with aria-labelledby or aria-label can be added to describe the component. In case avatars need to be tabbable, tabIndex can be added to implement custom key handlers.

Keyboard Support#

Component does not include any interactive elements.