Avatar

Avatars provide visual representation of users, accounts, or entities. They support multiple content types including icons, initials, and images, with optional status indicators to communicate presence or state information.

import {AvatarModule} from "@qualcomm-ui/angular/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:

q-avatar-root: The main component.
q-avatar-image: (optional) Displays an image as the avatar.
q-avatar-content: (optional) Displays alternative content, such as initials or an icon, and acts as a fallback if the image fails to load.
q-avatar-status: (optional) Shows a status indicator dot.

Examples

Showcase

Here's a typical usage example:

<div q-avatar status="active">
  <img alt="John Doe" q-avatar-image src="/images/avatar-man.png" />
  <div q-avatar-content>J</div>
  <div q-avatar-status></div>
</div>

Content

The q-avatar-content directive displays alternative content within the avatar. Use it by itself to show a single character or an icon, or together with q-avatar-image to provide fallback content if the image cannot be loaded.

Initials

Icon

Fallback

Initials
<div q-avatar>
  <div q-avatar-content>O</div>
</div>
Icon
<div q-avatar>
  <div q-avatar-content>
    <svg aria-label="User" qIcon="User"></svg>
  </div>
</div>
Fallback
<div q-avatar>
  <img alt="John Doe" q-avatar-image src="https://example.invalid" />
  <div q-avatar-content>J</div>
</div>

Sizes

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

XSmall

Small

Medium

Large

XLarge

XSmall
<div q-avatar size="xs">
  <img alt="Jane Doe" q-avatar-image src="/images/avatar-woman.png" />
  <div q-avatar-content>J</div>
</div>
Small
<div q-avatar size="sm">
  <img alt="Jane Doe" q-avatar-image src="/images/avatar-woman.png" />
  <div q-avatar-content>J</div>
</div>
Medium
<div q-avatar size="md">
  <img alt="Jane Doe" q-avatar-image src="/images/avatar-woman.png" />
  <div q-avatar-content>J</div>
</div>
Large
<div q-avatar size="lg">
  <img alt="Jane Doe" q-avatar-image src="/images/avatar-woman.png" />
  <div q-avatar-content>J</div>
</div>
XLarge
<div q-avatar size="xl">
  <img alt="Jane Doe" q-avatar-image src="/images/avatar-woman.png" />
  <div q-avatar-content>J</div>
</div>

Emphasis

When displaying initials or an icon, use the emphasis input to set the avatar's color. Available values are neutral (default), contrast, and brand.

Neutral

High Contrast

Brand

Neutral
<div emphasis="neutral" q-avatar>
  <div q-avatar-content>O</div>
</div>
High Contrast
<div emphasis="contrast" q-avatar>
  <div q-avatar-content>O</div>
</div>
Brand
<div emphasis="brand" q-avatar>
  <div q-avatar-content>O</div>
</div>

Status

To indicate the status of the user or entity, use the q-avatar-status directive and set its status input to one of: active, offline (default), away, or busy.

Active

Offline

Away

Busy

Active
<div q-avatar status="active">
  <img alt="Jane Doe" q-avatar-image src="/images/avatar-woman.png" />
  <div q-avatar-content>J</div>
  <div q-avatar-status></div>
</div>
Offline
<div q-avatar status="offline">
  <img alt="Jane Doe" q-avatar-image src="/images/avatar-woman.png" />
  <div q-avatar-content>J</div>
  <div q-avatar-status></div>
</div>
Away
<div q-avatar status="away">
  <img alt="Jane Doe" q-avatar-image src="/images/avatar-woman.png" />
  <div q-avatar-content>J</div>
  <div q-avatar-status></div>
</div>
Busy
<div q-avatar status="busy">
  <img alt="Jane Doe" q-avatar-image src="/images/avatar-woman.png" />
  <div q-avatar-content>J</div>
  <div q-avatar-status></div>
</div>

State Callback

You can listen for changes to the avatar's state by using the stateChanged output.

current state: loaded

current state: error

<div q-avatar (stateChanged)="currentStateValid.set($event.state)">
  <img alt="John Doe" q-avatar-image src="/images/avatar-man.png" />
  <div q-avatar-content>J</div>
</div>
<output>current state: {{ currentStateValid() }}</output>
<div q-avatar (stateChanged)="currentStateInvalid.set($event.state)">
  <img alt="John Doe" q-avatar-image src="https://example.invalid" />
  <div q-avatar-content>J</div>
</div>
<output>current state: {{ currentStateInvalid() }}</output>

Explorer

Component Anatomy

Hover to highlight, click to view API

root image status

API

q-avatar

Prop	Type
dir The document's text/writing direction.	'ltr' \| 'rtl'
emphasis Governs the color of the avatar.	\| 'neutral' \| 'contrast' \| 'brand'
id HTML id attribute. If omitted, a unique identifier will be generated for accessibility.)	string
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 ^* Deprecated use emphasis instead	\| 'neutral' \| 'contrast' \| 'brand'
(stateChanged) Function called when the avatar state is changed.	{ state: string }

dir

Type

'ltr' | 'rtl'

Description

The document's text/writing direction.

emphasis

Type

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

Description

Governs the color of the avatar.

Type

string

Description

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

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

Deprecated use emphasis instead

(stateChanged)

Type

{
  state: string
}

Description

Function called when the avatar state is changed.

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

class

Value

'qui-avatar__root'

data-avatar-part

Value

'root'

data-size

Value

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

q-avatar-image

Prop	Type
id id attribute. If omitted, a unique identifier will be generated for accessibility.)	string

Type

string

Description

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

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

class

Value

'qui-avatar__image'

data-avatar-part

Value

'image'

data-state

Value

| 'hidden'
| 'visible'

hidden

Value

boolean

q-avatar-content

Prop	Type
id id attribute. If omitted, a unique identifier will be generated for accessibility.)	string

Type

string

Description

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

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

class

Value

'qui-avatar__content'

data-avatar-part

Value

'content'

data-emphasis

Value

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

data-state

Value

| 'hidden'
| 'visible'

hidden

Value

boolean

q-avatar-status

Prop	Type
id id attribute. If omitted, a unique identifier will be generated for accessibility.)	string

Type

string

Description

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

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

class

Value

'qui-avatar__status'

data-avatar-part

Value

'status'

data-status

Value

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

Last updated on May 23, 2026 by Ryan Bower

Alert Banner

Icon Badge