QUI React2.6.3

Avatar

An avatar is a thumbnail representation of an entity, such as a user or an organization.

import {QAvatar} from "@qui/react"

Overview

By default, the Avatar renders as a clickable button element. It is recommended that you supply a descriptive aria-label to each element. You can change the root element using the as prop.

Examples

Variants

Use the variant property to alter the look and feel. When variant is set to text, supply content to set the content. Only the first two characters will apply.

TextIconImage
import {ReactNode} from "react"


import {User} from "lucide-react"


import {QAvatar} from "@qui/react"


export default function Variants(): ReactNode {
  return (
    <div className="grid justify-center">
      <div className="grid grid-cols-3 gap-x-8 gap-y-4">
        <span className="text-primary q-font-heading-xs">Text</span>
        <span className="text-primary q-font-heading-xs">Icon</span>
        <span className="text-primary q-font-heading-xs">Image</span>


        <QAvatar
          aria-label="Profile"
          color="brand"
          content="QC"
          variant="text"
        />
        <QAvatar
          aria-label="Profile"
          color="purple"
          icon={User}
          variant="icon"
        />
        <QAvatar
          aria-label="Profile"
          imgAlt="SH"
          imgSrc="/images/shashi.png"
          variant="image"
        />
      </div>
    </div>
  )
}

Shapes

Use the shape property to change the shape of the avatar to square. The default is round.

RoundSquare
import {ReactNode} from "react"


import {Smartphone} from "lucide-react"


import {QAvatar} from "@qui/react"


export default function Shapes(): ReactNode {
  return (
    <div className="grid justify-center">
      <div className="grid grid-cols-2 gap-x-8 gap-y-4">
        <span className="text-primary q-font-heading-xs">Round</span>
        <span className="text-primary q-font-heading-xs">Square</span>


        <QAvatar
          aria-label="Smartphone"
          color="magenta"
          icon={Smartphone}
          shape="round"
          size="l"
          variant="icon"
        />
        <QAvatar
          aria-label="Smartphone"
          color="magenta"
          icon={Smartphone}
          shape="square"
          size="l"
          variant="icon"
        />
      </div>
    </div>
  )
}

States

Use the disabled property to show that an avatar exist, but is not available or active.

TextIconImageEnabledDisabled
import {ReactNode} from "react"


import {Wifi} from "lucide-react"


import {QAvatar} from "@qui/react"


export default function States(): ReactNode {
  return (
    <div className="grid justify-center">
      <div className="grid grid-cols-4 grid-rows-3 items-center gap-x-8 gap-y-4">
        <div></div>
        <span className="text-primary q-font-heading-xs">Text</span>
        <span className="text-primary q-font-heading-xs">Icon</span>
        <span className="text-primary q-font-heading-xs">Image</span>


        <span className="text-primary q-font-heading-xs">Enabled</span>
        <QAvatar
          aria-label="Profile"
          color="blue"
          content="QC"
          onClick={() => alert("click is enabled!")}
          shape="round"
          size="l"
          variant="text"
        />
        <QAvatar
          aria-label="Wifi"
          color="purple"
          icon={Wifi}
          onClick={() => alert("click is enabled!")}
          shape="round"
          size="l"
          variant="icon"
        />
        <QAvatar
          aria-label="Profile"
          imgAlt="Shashi"
          imgSrc="/images/shashi.png"
          onClick={() => alert("click is enabled!")}
          shape="round"
          size="l"
          variant="image"
        />


        <span className="text-primary q-font-heading-xs">Disabled</span>
        <QAvatar
          aria-label="Profile"
          color="blue"
          content="QC"
          disabled
          onClick={() => alert("click should not be enabled!")}
          shape="round"
          size="l"
          variant="text"
        />
        <QAvatar
          aria-label="Profile"
          color="purple"
          disabled
          icon={Wifi}
          onClick={() => alert("click should not be enabled!")}
          shape="round"
          size="l"
          variant="icon"
        />
        <QAvatar
          aria-label="Profile"
          disabled
          imgAlt="Shashi"
          imgSrc="/images/shashi.png"
          onClick={() => alert("click should not be enabled!")}
          shape="round"
          size="l"
          variant="image"
        />
      </div>
    </div>
  )
}

Colors

Use the color property to set the color of avatar.

brandredorangeyellowkiwigreentealbluepurplefuchsiamagentaneutral
import {Fragment, ReactNode} from "react"


import {Monitor, User} from "lucide-react"


import {QAvatar} from "@qui/react"


import colors from "./avatar-colors"


export default function Colors(): ReactNode {
  return (
    <div className="grid justify-center">
      <div className="grid grid-cols-4 grid-rows-3 items-center gap-x-8 gap-y-4">
        {colors.map((color) => {
          return (
            <Fragment key={color}>
              <span className="text-primary q-font-heading-xs">{color}</span>
              <QAvatar
                aria-label="Profile"
                color={color}
                icon={User}
                shape="round"
                size="l"
                variant="icon"
              />
              <QAvatar
                aria-label="Monitor"
                color={color}
                icon={Monitor}
                shape="square"
                size="l"
                variant="icon"
              />
              <QAvatar
                aria-label="Profile"
                color={color}
                content="QC"
                shape="round"
                size="l"
                variant="text"
              />
            </Fragment>
          )
        })}
      </div>
    </div>
  )
}

Emphasis

Use the emphasis property to set subtle or strong style. Defaults to subtle.

SubtleStrongbrandredorangeyellowkiwigreentealbluepurplefuchsiamagentaneutral
import {Fragment, ReactNode} from "react"


import {User} from "lucide-react"


import {QAvatar} from "@qui/react"


import colors from "./avatar-colors"


export default function Variants(): ReactNode {
  return (
    <div className="grid justify-center">
      <div className="grid grid-cols-3 items-center gap-x-8 gap-y-4">
        <div></div>
        <span className="text-primary q-font-heading-xs">Subtle</span>
        <span className="text-primary q-font-heading-xs">Strong</span>
        {colors.map((color) => {
          return (
            <Fragment key={color}>
              <span className="text-primary q-font-heading-xs">{color}</span>
              <QAvatar
                aria-label="Profile"
                color={color}
                icon={User}
                shape="round"
                size="l"
                variant="icon"
              />
              <QAvatar
                aria-label="Profile"
                color={color}
                emphasis="strong"
                icon={User}
                shape="round"
                size="l"
                variant="icon"
              />
            </Fragment>
          )
        })}
      </div>
    </div>
  )
}

Sizes

Use the size property to set size of the avatar. There are five available values: xs, s, m, l, xl. Should you need more control over the rendered size, supply a number instead which will be converted to pixels. Use iconSize and fontSize to separately control the size of icon and text respectively.

import {ReactNode} from "react"


import {User} from "lucide-react"


import {QAvatarSize} from "@qui/base"
import {QAvatar} from "@qui/react"


const sizes: QAvatarSize[] = ["xs", "s", "m", "l", "xl"]


export default function Sizes(): ReactNode {
  return (
    <div className="grid justify-center gap-4">
      <div className="flex items-end justify-center gap-4">
        {sizes.map((size) => (
          <QAvatar
            key={size}
            aria-label="Profile"
            color="purple"
            icon={User}
            shape="round"
            size={size}
            variant="icon"
          />
        ))}
      </div>
      <div className="flex items-center justify-center gap-4">
        <QAvatar
          aria-label="Profile"
          color="purple"
          icon={User}
          iconSize="24"
          shape="round"
          size="50"
          variant="icon"
        />
        <QAvatar
          aria-label="Profile"
          color="brand"
          content="QC"
          fontSize="26"
          shape="round"
          size="57"
          variant="text"
        />
        <QAvatar
          aria-label="Profile"
          imgAlt="Shashi"
          imgSrc="/images/shashi.png"
          shape="round"
          size="65"
          variant="image"
        />
      </div>
    </div>
  )
}

API

Props

Name & DescriptionOption(s)Default
as
The component used for the root node. It can be a React component or element.
| ElementType
| ComponentType
'button'
className
The className property of the Element interface gets and sets the value of the class attribute of the specified element.
string
clickable
If true, the avatar will be clickable.
boolean
true
color
The color variant of the avatar.
| 'brand'
| 'red'
| 'orange'
| 'yellow'
| 'kiwi'
| 'green'
| 'teal'
| 'blue'
| 'purple'
| 'fuchsia'
| 'magenta'
| 'neutral'
'neutral'
content
The avatar's string content. This value only applies when variant is 'text'. Due to size constraints, only the first two characters are rendered.
string
disabled
If true, the component is disabled.
boolean
false
emphasis
The style emphasis of the avatar.
| 'subtle'
| 'strong'
'subtle'
fontSize
The font-size of the avatar's text content. If omitted, the font size will be computed using a preset value based on the size input. If supplied as a number, the value will be applied as px. Otherwise, the string value of the property will apply.
| string
| number
icon
lucide-react icon, positioned in the center of the component. Does nothing if variant is anything other than icon.
| LucideIcon
| ReactNode
iconSize
Override the size of the endIcon. Provide one of the preset sizes, or customize with a number or string. If supplied as a number, the value will be applied as px. Otherwise, the string value of the property will apply. If this property is omitted, the size is used as a fallback.
| 'xs'
| 's'
| 'm'
| 'l'
| 'xl'
| string
| number
imgAlt
HTML img alt attribute. Does nothing is variant is anything other than 'image'.
string
imgSrc
HTML img src attribute. Does nothing is variant is anything other than 'image'.
string
shape
The shape of the avatar.
| 'round'
| 'square'
'round'
size
The size of the avatar. If supplied as a number, the value will be applied as px. Otherwise, the string value of the property will apply.
| 'xs'
| 's'
| 'm'
| 'l'
| 'xl'
| string
| number
'm'
style
The style global attribute contains CSS styling declarations to be applied to the element.
CSSProperties
variant
The variant of the avatar.
| 'icon'
| 'text'
| 'image'
'text'
Type
| ElementType
| ComponentType
Default
'button'
Description
The component used for the root node. It can be a React component or element.
Type
string
Description
The className property of the Element interface gets and sets the value of the class attribute of the specified element.
Type
boolean
Default
true
Description
If true, the avatar will be clickable.
Type
| 'brand'
| 'red'
| 'orange'
| 'yellow'
| 'kiwi'
| 'green'
| 'teal'
| 'blue'
| 'purple'
| 'fuchsia'
| 'magenta'
| 'neutral'
Default
'neutral'
Description
The color variant of the avatar.
content
Type
string
Description
The avatar's string content. This value only applies when variant is 'text'. Due to size constraints, only the first two characters are rendered.
Type
boolean
Default
false
Description
If true, the component is disabled.
Type
| 'subtle'
| 'strong'
Default
'subtle'
Description
The style emphasis of the avatar.
Type
| string
| number
Description
The font-size of the avatar's text content. If omitted, the font size will be computed using a preset value based on the size input. If supplied as a number, the value will be applied as px. Otherwise, the string value of the property will apply.
Type
| LucideIcon
| ReactNode
Description
lucide-react icon, positioned in the center of the component. Does nothing if variant is anything other than icon.
Type
| 'xs'
| 's'
| 'm'
| 'l'
| 'xl'
| string
| number
Description
Override the size of the endIcon. Provide one of the preset sizes, or customize with a number or string. If supplied as a number, the value will be applied as px. Otherwise, the string value of the property will apply. If this property is omitted, the size is used as a fallback.
Type
string
Description
HTML img alt attribute. Does nothing is variant is anything other than 'image'.
Type
string
Description
HTML img src attribute. Does nothing is variant is anything other than 'image'.
Type
| 'round'
| 'square'
Default
'round'
Description
The shape of the avatar.
Type
| 'xs'
| 's'
| 'm'
| 'l'
| 'xl'
| string
| number
Default
'm'
Description
The size of the avatar. If supplied as a number, the value will be applied as px. Otherwise, the string value of the property will apply.
Type
CSSProperties
Description
The style global attribute contains CSS styling declarations to be applied to the element.
Type
| 'icon'
| 'text'
| 'image'
Default
'text'
Description
The variant of the avatar.
Previous
Accordion
Next
Badge
Overview
Examples
Variants
Shapes
States
Colors
Emphasis
Sizes
API
Props
Copyright © 2025 QUALCOMM incorporated. All rights reserved. This site is built using QUI Docs. Head over to the template repository to start building.