Avatar

A non-interactive circle that represents an entity — with an image, initials, or an icon.

Usage

forge-avatar represents an entity through imageUrl, text (rendered as initials via letterCount), or a slotted icon when neither is set. Use it for people, accounts, or records that are genuinely identifiable by image or initials, most often in a list, table row, card, or navigation header. Skip it when the image or initials add no real information, like using a category’s first letter as a stand-in avatar.

Rules

Use a real photo when one is likely to be available and the person is likely to be recognizable.

Fall back to initials when no image is available, rather than leaving the avatar empty.

Use a larger avatar in a card or profile header, and a smaller one in a list or table row.

Don't

Don't use an avatar when the image or initials don't add information — an icon or plain text may fit better.

Don't rely on an avatar's initials alone to distinguish records with the same first letter — pair it with a visible name.

Don't imply interactivity — avatars have no hover or focus state of their own.

Basic usage

Set text for an avatar that renders initials — by default, the first letter of each word, controlled by letterCount.

An avatar rendering initials from its text.

<forge-avatar text="Tyler Forge">
</forge-avatar>

With an icon

Slot a forge-icon instead of setting text or imageUrl when the avatar represents something other than a named person — like a generic account or object type.

An icon slotted in place of text or an image.

<forge-avatar>
  <forge-icon name="person">
  </forge-icon>
</forge-avatar>

<script type="module">
import { IconRegistry } from "@tylertech/forge/icon";
import { tylIconPerson } from "@tylertech/tyler-icons";
IconRegistry.define([tylIconPerson]);
</script>

With an image

Set imageUrl to show a photo instead of initials or an icon.

An avatar showing a photo instead of initials.

<forge-avatar image-url="./ruby.jpg">
</forge-avatar>

Avatars represent an entity via text or image. Use avatars to visually represent users, objects, or identifiers in your application.

import "@tylertech/forge/avatar";

Properties

Property	Attribute	Type	Default	Description
`text`	`text`	`string`	`''`	The text to display in the avatar.
`letterCount`	`letter-count`	`number`	`2`	Controls the number of letters to display from the text. By default the text is split on spaces and the first character of each word is used.
`imageUrl`	`image-url`	`string`	`''`	The background image URL to use.

Slots

Name	Description
`(default)`	The default slot for avatar content if not provided via text/imageUrl.

CSS Parts

Name	Description
`::part(root)`	The root container element.
`::part(empty-image)`	The empty image container element.

CSS Custom Properties

Name	Description
`--forge-avatar-background`	The background color of the avatar.
`--forge-avatar-shape`	The border radius of the avatar, defaults to 50%.
`--forge-avatar-color`	The text color of the avatar.
`--forge-avatar-size`	The height and width of the avatar.
`--forge-avatar-transition-duration`	The transition duration for animations.
`--forge-avatar-transition-timing`	The transition timing function for animations.
`--forge-theme-surface-container-low`	The background color of the empty image.
`--forge-theme-surface-container-high`	The foreground color of the empty image.

An avatar isn’t inherently meaningful to assistive technology. Add aria-hidden="true" when one is purely decorative, and avoid relying on an avatar for essential navigation.

Composing with an icon button

When an avatar is nested inside an icon button — a profile trigger, for example — give the icon button its own accessible label. The avatar’s image or initials aren’t announced as a label on their own.

Color and contrast

If an avatar’s color conveys meaning, such as a status ring, pair it with another visual cue for users with color vision deficiencies. Foreground text still needs to meet WCAG 2.2 contrast requirements against the background.