Skip to main content
The @zendeskgarden/react-avatars package provides the Avatar and StatusIndicator components. Use Avatar to represent a user or system with an image, icon, or initials. Use StatusIndicator as a standalone presence badge.

​
Installation

npm install @zendeskgarden/react-avatars

# Peer dependencies
npm install react react-dom styled-components @zendeskgarden/react-theming

​
Avatar

Avatar renders a single child — an <img>, an SVG icon, or an Avatar.Text — inside a styled container. Wrap your app in ThemeProvider before using any Garden component. 
import { ThemeProvider } from '@zendeskgarden/react-theming';
import { Avatar } from '@zendeskgarden/react-avatars';

const App = () => (
  <ThemeProvider>
    <Avatar>
      <img src="/images/user.png" alt="Jane Doe" />
    </Avatar>
  </ThemeProvider>
);

​
Size

The size prop controls the avatar dimensions. The default is medium. 
<Avatar size="extraextrasmall">
  <img src="/images/user.png" alt="Jane Doe" />
</Avatar>

<Avatar size="extrasmall">
  <img src="/images/user.png" alt="Jane Doe" />
</Avatar>

<Avatar size="small">
  <img src="/images/user.png" alt="Jane Doe" />
</Avatar>

<Avatar size="medium">
  <img src="/images/user.png" alt="Jane Doe" />
</Avatar>

<Avatar size="large">
  <img src="/images/user.png" alt="Jane Doe" />
</Avatar>

​
Status

Set the status prop to show a presence indicator on the avatar. When status is set, also provide a statusLabel for screen readers. 
<Avatar status="available" statusLabel="status: available">
  <img src="/images/user.png" alt="Jane Doe" />
</Avatar>

<Avatar status="away" statusLabel="status: away">
  <img src="/images/user.png" alt="Jane Doe" />
</Avatar>

<Avatar status="transfers" statusLabel="status: transfers">
  <img src="/images/user.png" alt="Jane Doe" />
</Avatar>

<Avatar status="offline" statusLabel="status: offline">
  <img src="/images/user.png" alt="Jane Doe" />
</Avatar>
Status valueVisual meaning
availableGreen indicator — agent is online and available
awayYellow indicator with clock icon — agent is away
transfersBlue indicator with arrow icon — agent accepts transfers
offlineGrey indicator — agent is offline

​
Badge

Set the badge prop to display a notification count. The status prop is overridden to active when badge is provided. 
<Avatar badge={3} statusLabel="status: active. 3 notifications">
  <img src="/images/user.png" alt="Jane Doe" />
</Avatar>

<Avatar badge={0} statusLabel="status: active. no notifications">
  <img src="/images/user.png" alt="Jane Doe" />
</Avatar>

​
System avatars

Set isSystem to apply styling intended for objects, brands, or products rather than people. 
import ZendeskIcon from '@zendeskgarden/svg-icons/src/26/zendesk.svg';

<Avatar isSystem backgroundColor="background.emphasis" foregroundColor="foreground.onEmphasis">
  <ZendeskIcon />
</Avatar>

​
Avatar.Text

Use Avatar.Text as the child of Avatar to display initials or short text. 
<Avatar backgroundColor="background.emphasis" foregroundColor="foreground.onEmphasis">
  <Avatar.Text>GD</Avatar.Text>
</Avatar>

​
Props

​
size
'extraextrasmall' | 'extrasmall' | 'small' | 'medium' | 'large'
default:"'medium'"
Sets the avatar dimensions.
​
status
'available' | 'away' | 'transfers' | 'offline'
Applies a presence indicator to the avatar.
​
statusLabel
string
Accessible label for the status indicator. Required when status is set and the avatar is not aria-hidden.
​
badge
string | number
Displays a notification count and sets the status to active. Takes precedence over the status prop.
​
backgroundColor
string
Sets the avatar background color. Accepts a theme color variable key (e.g. background.emphasis) or a hex value.
​
foregroundColor
string
Sets the color for child SVG or Avatar.Text content. Accepts a theme color variable key (e.g. foreground.onEmphasis) or a hex value.
​
surfaceColor
string
Provides a surface color for avatars placed on non-default backgrounds. Accepts a theme color variable key or a hex value.
​
isSystem
boolean
Applies system styling for representing objects, brands, or products.

​
StatusIndicator

StatusIndicator is a standalone presence component — use it outside of an Avatar when you need to show a user’s status alongside their name or in a list. 
import { ThemeProvider } from '@zendeskgarden/react-theming';
import { StatusIndicator } from '@zendeskgarden/react-avatars';

const App = () => (
  <ThemeProvider>
    <StatusIndicator type="available">Available</StatusIndicator>
    <StatusIndicator type="away">Away</StatusIndicator>
    <StatusIndicator type="transfers">Transfers</StatusIndicator>
    <StatusIndicator type="offline">Offline</StatusIndicator>
  </ThemeProvider>
);
StatusIndicator renders a role="status" live region. Its icon uses role="img" with an auto-generated aria-label based on the type value. Override the label with the aria-label prop, or pass null to mark it as decorative.

​
Compact styling

Use isCompact to reduce the indicator size, for example inside dense list rows. 
<StatusIndicator type="available" isCompact>
  Available
</StatusIndicator>

​
Props

​
type
'available' | 'away' | 'transfers' | 'offline'
default:"'offline'"
Applies status styling and sets the default accessible label.
​
aria-label
string | null
Overrides the auto-generated label. Pass null to mark the indicator as decorative and suppress the label.
​
isCompact
boolean
Applies compact styling with smaller icons.

Build docs developers (and LLMs) love

Get started for freeTalk to us