Avatar

Avatars are used to represent a user or an entity in the UI. They can be used in various contexts, such as user profiles, comments, or lists.

import {Avatar} from "@qualcomm-ui/react/avatar"

Usage

Avatars can display a user or entity image, initials, or custom content when an image is unavailable. They can also indicate the status of the user or entity.

Overview

The anatomy of the avatar component is as follows:

Avatar.Root: The main component.
Avatar.Image: (optional) Displays an image as the avatar.
Avatar.Content: (optional) Displays alternate content, such as initials or an icon, and acts as a fallback if the image fails to load..
Avatar.Status: (optional) Shows a status indicator dot.

Examples

Showcase

Here's a typical usage example:

Brand

<Avatar.Root status="active">
  <Avatar.Image alt="John Doe" src="/images/avatar-man.png" />
  <Avatar.Content>JD</Avatar.Content>
  <Avatar.Status />
</Avatar.Root>

The Avatar.Content component displays alternative content within the avatar. Use it by itself to show initials or an icon, or together with Avatar.Image to provide fallback content if the image cannot be loaded.

Brand

Initials

Icon

Fallback

Initials
<Avatar.Root>
  <Avatar.Content>OK</Avatar.Content>
</Avatar.Root>
Icon
<Avatar.Root>
  <Avatar.Content icon={User} />
</Avatar.Root>
Fallback
<Avatar.Root>
  <Avatar.Image alt="John Doe" src="https://example.invalid" />
  <Avatar.Content>JD</Avatar.Content>
</Avatar.Root>

Sizes

Use the size prop to set the size of the avatar. The available sizes are xs, sm, md (default), lg, and xl.

Brand


{sizes.map((size) => (
  <div key={size} className="flex flex-col items-center gap-2">
    <Avatar.Root size={size}>
      <Avatar.Image alt="Jane Doe" src="/images/avatar-woman.png" />
      <Avatar.Content>JD</Avatar.Content>
    </Avatar.Root>
    {size}
  </div>
))}

Variants

When displaying initials or an icon, use the variant prop on Avatar.Content to set the avatar's style. Available variants are neutral (default), contrast, and brand.

Brand

Neutral

High Contrast

Brand

Neutral
<Avatar.Root variant="neutral">
  <Avatar.Content>OK</Avatar.Content>
</Avatar.Root>
High Contrast
<Avatar.Root variant="contrast">
  <Avatar.Content>OK</Avatar.Content>
</Avatar.Root>
Brand
<Avatar.Root variant="brand">
  <Avatar.Content>OK</Avatar.Content>
</Avatar.Root>

Status

To indicate the status of the user or entity, use the Avatar.Status component and set its status prop to one of: active, offline (default), away, or busy.

Brand

Active

Offline

Away

Busy

Active
<Avatar.Root status="active">
  <Avatar.Image alt="Jane Doe" src="/images/avatar-woman.png" />
  <Avatar.Content>JD</Avatar.Content>
  <Avatar.Status />
</Avatar.Root>
Offline
<Avatar.Root status="offline">
  <Avatar.Image alt="Jane Doe" src="/images/avatar-woman.png" />
  <Avatar.Content>JD</Avatar.Content>
  <Avatar.Status />
</Avatar.Root>
Away
<Avatar.Root status="away">
  <Avatar.Image alt="Jane Doe" src="/images/avatar-woman.png" />
  <Avatar.Content>JD</Avatar.Content>
  <Avatar.Status />
</Avatar.Root>
Busy
<Avatar.Root status="busy">
  <Avatar.Image alt="Jane Doe" src="/images/avatar-woman.png" />
  <Avatar.Content>JD</Avatar.Content>
  <Avatar.Status />
</Avatar.Root>

State Callback

You can listen for changes to the avatar's state by using the onStateChange prop.

Brand

current state:

import {type ReactElement, useState} from "react"

import {Avatar} from "@qualcomm-ui/react/avatar"

export default function AvatarStateCallbackDemo(): ReactElement {
  const [currentStateValid, setCurrentStateValid] = useState<string | null>(
    null,
  )
  const [currentStateInvalid, setCurrentStateInvalid] = useState<string | null>(
    null,
  )
  return (
    <div className="flex items-center gap-4">
      <Avatar.Root onStateChange={(event) => setCurrentStateValid(event.state)}>
        <Avatar.Image alt="John Doe" src="/images/avatar-man.png" />
        <Avatar.Content>JD</Avatar.Content>
      </Avatar.Root>
      <output>current state: {currentStateValid}</output>
      <Avatar.Root
        onStateChange={(event) => setCurrentStateInvalid(event.state)}
      >
        <Avatar.Image alt="John Doe" src="https://example.invalid" />
        <Avatar.Content>JD</Avatar.Content>
      </Avatar.Root>
      <output>current state: {currentStateInvalid}</output>
    </div>
  )
}

API

<Avatar.Root>

Displays a user's profile picture, initials, or fallback icon. Renders a <span> element by default.

Prop	Type	Default
children React children prop.	ReactNode
dir The document's text/writing direction.	'ltr' \| 'rtl'	'ltr'
id id attribute. If omitted, a unique identifier will be automatically generated for accessibility.	string
onStateChange	(event: { state: string }) => void
render Allows you to replace the component's HTML element with a different tag or component. Learn more	\| ReactElement \| (( props: object, ) => ReactElement)
size Governs the width and height of the avatar as well as the font size of its content.	\| 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'
status Optional status for the avatar, renders a dot indicator next to the avatar.	\| 'offline' \| 'active' \| 'away' \| 'busy'
variant The style variant of the avatar.	\| 'neutral' \| 'contrast' \| 'brand'

children

Type

ReactNode

Description

React children prop.

dir

Type

'ltr' | 'rtl'

Description

The document's text/writing direction.

Type

string

Description

id attribute. If omitted, a unique identifier will be automatically generated for accessibility.

onStateChange

Type

(event: {
  state: string
}) => void

render

Type

| ReactElement
| ((
    props: object,
  ) => ReactElement)

Description

Allows you to replace the component's HTML element with a different tag or component. Learn more

size

Type

| 'xs'
| 'sm'
| 'md'
| 'lg'
| 'xl'

Description

Governs the width and height of the avatar as well as the font size of its content.

status

Type

| 'offline'
| 'active'
| 'away'
| 'busy'

Description

Optional status for the avatar, renders a dot indicator next to the avatar.

variant

Type

| 'neutral'
| 'contrast'
| 'brand'

Description

The style variant of the avatar.

Attribute / Property	Value
`className`	'qui-avatar__root'
`data-part`	'root'
`data-scope`	'avatar'
`data-size`	\| 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'

className

Value

'qui-avatar__root'

data-part

Value

'root'

data-scope

Value

'avatar'

data-size

Value

| 'xs'
| 'sm'
| 'md'
| 'lg'
| 'xl'

<Avatar.Image>

The image to display in the avatar. Renders an <img> element by default.

Prop	Type
children React children prop.	ReactNode
id id attribute. If omitted, a unique identifier will be automatically generated for accessibility.	string
render Allows you to replace the component's HTML element with a different tag or component. Learn more	\| ReactElement \| (( props: object, ) => ReactElement)

children

Type

ReactNode

Description

React children prop.

Type

string

Description

id attribute. If omitted, a unique identifier will be automatically generated for accessibility.

render

Type

| ReactElement
| ((
    props: object,
  ) => ReactElement)

Description

Allows you to replace the component's HTML element with a different tag or component. Learn more

Attribute / Property	Value
`data-part`	'image'
`data-scope`	'avatar'
`data-state`	\| 'hidden' \| 'visible'
`hidden`	boolean

data-part

Value

'image'

data-scope

Value

'avatar'

data-state

Value

| 'hidden'
| 'visible'

hidden

Value

boolean

<Avatar.Content>

Displays alternate content, such as initials or an icon, and acts as a fallback if the image fails to load. Renders a <span> element by default.

Prop	Type
children React children prop.	ReactNode
icon Icon content.	\| ReactNode \| LucideIcon
id id attribute. If omitted, a unique identifier will be automatically generated for accessibility.	string
render Allows you to replace the component's HTML element with a different tag or component. Learn more	\| ReactElement \| (( props: object, ) => ReactElement)

children

Type

ReactNode

Description

React children prop.

icon

Type

| ReactNode
| LucideIcon

Description

Icon content.

Type

string

Description

id attribute. If omitted, a unique identifier will be automatically generated for accessibility.

render

Type

| ReactElement
| ((
    props: object,
  ) => ReactElement)

Description

Allows you to replace the component's HTML element with a different tag or component. Learn more

Attribute / Property	Value
`className`	'qui-avatar__content'
`data-part`	'content'
`data-scope`	'avatar'
`data-state`	\| 'hidden' \| 'visible'
`data-variant`	\| 'neutral' \| 'contrast' \| 'brand'
`hidden`	boolean

className

Value

'qui-avatar__content'

data-part

Value

'content'

data-scope

Value

'avatar'

data-state

Value

| 'hidden'
| 'visible'

data-variant

Value

| 'neutral'
| 'contrast'
| 'brand'

hidden

Value

boolean

<Avatar.Status>

Displays a status indicator dot for the avatar. Renders a <div> element by default.

Prop	Type
children React children prop.	ReactNode
id id attribute. If omitted, a unique identifier will be automatically generated for accessibility.	string
render Allows you to replace the component's HTML element with a different tag or component. Learn more	\| ReactElement \| (( props: object, ) => ReactElement)

children

Type

ReactNode

Description

React children prop.

Type

string

Description

id attribute. If omitted, a unique identifier will be automatically generated for accessibility.

render

Type

| ReactElement
| ((
    props: object,
  ) => ReactElement)

Description

Allows you to replace the component's HTML element with a different tag or component. Learn more

Attribute / Property	Value
`className`	'qui-avatar__status'
`data-part`	'status'
`data-scope`	'avatar'
`data-status`	\| 'offline' \| 'active' \| 'away' \| 'busy'

className

Value

'qui-avatar__status'

data-part

Value

'status'

data-scope

Value

'avatar'

data-status

Value

| 'offline'
| 'active'
| 'away'
| 'busy'

Text Input

Divider