Skip to main content
cngx-src documentation

CngxAvatar

ComponentPrimaryOnPushNo encapsulationv0.1.0WCAG AA

projects/common/display/avatar/avatar.component.ts

GitHub

Import#

import { CngxAvatar } from '@cngx/common/display'

Description#

Display atom for user/person/entity avatars.

Rendering cascade:

  1. Image (src set and not errored).
  2. Initials (initials set).
  3. Projected content (<ng-content>) - typically a <cngx-icon>.

Optional status indicator dot via status. Size and shape driven by CSS custom properties.

https://cngxjs.github.io/cngx/examples/#/common/display/avatar/cascade-image-initials-fallback https://cngxjs.github.io/cngx/examples/#/common/display/avatar/shapes-and-status https://cngxjs.github.io/cngx/examples/#/common/display/avatar/sizes

Related#

Metadata#

Selector
cngx-avatar
Export as
cngxAvatar
Change detection
ChangeDetectionStrategy.OnPush
Encapsulation
ViewEncapsulation.None
Style URLs
./avatar.component.css

Host#

Class
cngx-avatar
Bound classes
cngx-avatar--xs ← size() === "xs" cngx-avatar--sm ← size() === "sm" cngx-avatar--md ← size() === "md" cngx-avatar--lg ← size() === "lg" cngx-avatar--xl ← size() === "xl" cngx-avatar--square ← shape() === "square" cngx-avatar--circle ← shape() === "circle"

Index#

Properties

imageLoaded

Methods

handleErrorhandleLoad

Inputs

altinitialsshapesizesrcstatus

Derived State

showFallbackshowImage

HostBindings

class.cngx-avatar--xsclass.cngx-avatar--smclass.cngx-avatar--mdclass.cngx-avatar--lgclass.cngx-avatar--xlclass.cngx-avatar--squareclass.cngx-avatar--circle

Inputs#

alt#string | undefined
input()

Alternate text for the image. Required when src is used.

initials#string | undefined
input()

Initials fallback used when no image loads.

shape#"circle" | "square"
input()

Visual shape.

default 'circle'
size#"xs" | "sm" | "md" | "lg" | "xl"
input()

Size preset driving CSS custom properties on the host.

default 'md'
src#string | undefined
input()

Image URL. When set and loads successfully, the image is shown.

status#'online' | 'offline' | 'busy' | 'away' | undefined
input()

Optional user-presence status indicator.

Instance Properties#

imageLoaded#unknown
Readonly

Whether the image loaded successfully.

this.imageLoadedState.asReadonly()

Methods#

handleError#void
Protected
handleLoad#void
Protected

HostBindings#

BindingExpression
[class.cngx-avatar--xs]size() === "xs"
[class.cngx-avatar--sm]size() === "sm"
[class.cngx-avatar--md]size() === "md"
[class.cngx-avatar--lg]size() === "lg"
[class.cngx-avatar--xl]size() === "xl"
[class.cngx-avatar--square]shape() === "square"
[class.cngx-avatar--circle]shape() === "circle"

Default visuals for CngxAvatar. The host carries .cngx-avatar - an inline-flex plate that renders an image, an initials block, or projected content. Size and shape are driven by modifier classes, each backed by a token, so a consumer can either swap one variant globally or pin a specific instance via inline --cngx-avatar-*.

Shape variants

  • --circle - pill radius (--cngx-radius-pill)
  • --square - 6px rounded corner

Size variants

Each size pins both --cngx-avatar-size and --cngx-avatar-font-size to the matching scale step:

  • --xs - 1.5rem / 0.625rem
  • --sm - 2rem / 0.75rem
  • --md - 2.5rem / 1rem (default)
  • --lg - 3rem / 1.125rem
  • --xl - 4rem / 1.5rem

Slots

  • .cngx-avatar__img - cover-fit image, inherits border-radius
  • .cngx-avatar__initials - uppercased text block
  • .cngx-avatar__status - corner-positioned status dot

Status modifiers

  • __status--online - success-coded
  • __status--offline - neutral
  • __status--busy - danger-coded
  • __status--away - warning-coded

Inheritance

  • --cngx-avatar-bg -> --cngx-color-border
  • --cngx-avatar-color -> --cngx-color-text
  • --cngx-avatar-circle-radius -> --cngx-radius-pill
  • --cngx-avatar-status-border -> --cngx-color-surface
  • --cngx-avatar-status-online -> --cngx-color-success
  • --cngx-avatar-status-busy -> --cngx-color-danger
  • --cngx-avatar-status-away -> --cngx-color-warning
  • --cngx-avatar-status-offline - leaf neutral token

Dark mode

Three hooks invert the initials plate to a mid-gray surface with light text and flip the status-dot ring to track the dark page surface so the dot still reads as cut out of the avatar:

  • prefers-color-scheme: dark
  • [data-color-scheme="dark"] / .dark class
  • [data-color-scheme="light"] / .light class (explicit pin)

Index#

Layout

--cngx-avatar-size

Typography

--cngx-avatar-font-size

Surface

--cngx-avatar-bg--cngx-avatar-color

Variant / Shape

--cngx-avatar-circle-radius--cngx-avatar-square-radius

Variant / Size

--cngx-avatar-size-xs--cngx-avatar-size-sm--cngx-avatar-size-md--cngx-avatar-size-lg--cngx-avatar-size-xl--cngx-avatar-font-size-xs--cngx-avatar-font-size-sm--cngx-avatar-font-size-md--cngx-avatar-font-size-lg--cngx-avatar-font-size-xl

State / Status

--cngx-avatar-status-size--cngx-avatar-status-border--cngx-avatar-status-bg--cngx-avatar-status-online--cngx-avatar-status-offline--cngx-avatar-status-busy--cngx-avatar-status-away

Layout

--cngx-avatar-size#*
Default value 2.5rem

Active size of the avatar - consumed by the :scope rule and pinned by the size-variant classes.

Typography

--cngx-avatar-font-size#*
Default value 1rem

Active font-size of the initials block. Scaled in step with --cngx-avatar-size by the size-variant classes.

Surface

--cngx-avatar-bg#<color>
Default value oklch(0.92 0.01 240)

Background of the avatar plate. Defaults to the foundation border tone so an avatar without an image still reads as a neutral surface.

--cngx-avatar-color#<color>
Default value oklch(0.28 0 0)

Text color of the initials block.

Variant / Shape

--cngx-avatar-circle-radius#<length>
Default value 999px

Corner radius applied by .cngx-avatar--circle (pill default).

--cngx-avatar-square-radius#<length>
Default value 6px

Corner radius applied by .cngx-avatar--square.

Variant / Size

--cngx-avatar-size-xs#*
Default value 1.5rem

Size token for the .cngx-avatar--xs variant.

--cngx-avatar-size-sm#*
Default value 2rem

Size token for the .cngx-avatar--sm variant.

--cngx-avatar-size-md#*
Default value 2.5rem

Size token for the .cngx-avatar--md variant (default).

--cngx-avatar-size-lg#*
Default value 3rem

Size token for the .cngx-avatar--lg variant.

--cngx-avatar-size-xl#*
Default value 4rem

Size token for the .cngx-avatar--xl variant.

--cngx-avatar-font-size-xs#*
Default value 0.625rem

Font-size token for the .cngx-avatar--xs initials.

--cngx-avatar-font-size-sm#*
Default value 0.75rem

Font-size token for the .cngx-avatar--sm initials.

--cngx-avatar-font-size-md#*
Default value 1rem

Font-size token for the .cngx-avatar--md initials (default).

--cngx-avatar-font-size-lg#*
Default value 1.125rem

Font-size token for the .cngx-avatar--lg initials.

--cngx-avatar-font-size-xl#*
Default value 1.5rem

Font-size token for the .cngx-avatar--xl initials.

State / Status

--cngx-avatar-status-size#*
Default value 0.65em

Diameter of the status dot, expressed in em so it scales with the avatar's font-size.

--cngx-avatar-status-border#<color>
Default value oklch(1 0 0)

Ring color around the status dot - defaults to the surface color so the dot reads as cut out of the avatar.

--cngx-avatar-status-bg#<color>
Default value oklch(0.68 0.01 240)

Fallback background of the status dot when no state modifier is applied.

--cngx-avatar-status-online#<color>
Default value oklch(0.68 0.18 145)

Dot color for the .cngx-avatar__status--online modifier.

See: [[--cngx-color-success]]

--cngx-avatar-status-offline#<color>
Default value oklch(0.68 0.01 240)

Dot color for the .cngx-avatar__status--offline modifier.

--cngx-avatar-status-busy#<color>
Default value oklch(0.62 0.22 25)

Dot color for the .cngx-avatar__status--busy modifier.

See: [[--cngx-color-danger]]

--cngx-avatar-status-away#<color>
Default value oklch(0.72 0.18 70)

Dot color for the .cngx-avatar__status--away modifier.

See: [[--cngx-color-warning]]

Enter to selectArrow Down Arrow Up to navigateEsc to close