Primitives

Avatar

Display an image that represents a user with a text fallback.

Profile ImageNG

Import

Import the Avatar primitives from ng-primitives/avatar.

import { NgpAvatar, NgpAvatarImage, NgpAvatarFallback } from 'ng-primitives/avatar';

Usage

Assemble the avatar directives in your template.

<span ngpAvatar>
  <img ngpAvatarImage src="..." alt="..." />
  <span ngpAvatarFallback>NG</span>
</span>

Reusable Component

Create a reusable component that uses the NgpAvatar directive.

import { Component } from '@angular/core';
import { Avatar } from './avatar';

@Component({
  selector: 'app-root',
  imports: [Avatar],
  template: `
    <app-avatar image="https://mighty.tools/mockmind-api/content/human/104.jpg" fallback="AH" />
  `,
})
export default class App {}

Schematics

Generate a reusable avatar component using the Angular CLI.

ng g ng-primitives:primitive avatar

Options

  • path: The path at which to create the component file.
  • prefix: The prefix to apply to the generated component selector.
  • componentSuffix: The suffix to apply to the generated component class name.
  • fileSuffix: The suffix to apply to the generated component file name. Defaults to component.
  • exampleStyles: Whether to include example styles in the generated component file. Defaults to true.

API Reference

The following directives are available to import from the ng-primitives/avatar package:

NgpAvatar

Apply the `ngpAvatar` directive to an element that represents the avatar. This directive is a container for the image and/or fallback.

  • Selector: [ngpAvatar]
  • Exported As: ngpAvatar

Data Attributes

Attribute Description Value
data-status The loading status of the avatar image. idle | loading | loaded | error
data-hover The added to the avatar when hovered. -
data-focus-visible The added to the avatar when focus visible. -
data-press The added to the avatar when pressed. -

NgpAvatarImage

Apply the `ngpAvatarImage` directive to an element that represents the avatar image. This would typically be an `img` element or a `div` with a background image.

  • Selector: img[ngpAvatarImage]
  • Exported As: ngpAvatarImage

NgpAvatarFallback

Apply the `ngpAvatarFallback` directive to an element that represents the user in the absence of an image. This is typically the user's initials.

  • Selector: [ngpAvatarFallback]
  • Exported As: ngpAvatarFallback
ngpAvatarFallbackDelay
number
default: "0"

Define a delay before the fallback is shown. This is useful to only show the fallback for those with slower connections.

Global Configuration

You can configure the default options for all avatars in your application by using the provideAvatarConfig function in a providers array.

import { provideAvatarConfig } from 'ng-primitives/avatar';

bootstrapApplication(AppComponent, {
  providers: [provideAvatarConfig({ delay: 1000 })],
});

NgpAvatarConfig

delay
number

Define a delay before the fallback is shown. This is useful to only show the fallback for those with slower connections.

Copyright © 2025 Angular Primitives