Avatar
<cs-avatar>
Avatars represent a person or object with an image, initials, or icon. Use them in lists, comments, and profiles to give users visual context at a glance.
By default, a generic icon will be shown. You can personalize avatars by adding images, initials, and custom icons. You should always provide a label for assistive devices.
Examples
Image
To use an image for the avatar, set the image and label attributes. This will take priority and be shown over initials and icons.
Avatar images can be lazily loaded by setting the loading attribute to lazy.
Initials
When you don’t have an image to use, you can set the initials attribute to show something more personalized than an icon.
Custom Icon
When no image or initials are set, an icon will be shown. The default avatar shows a generic “user” icon, but you can customize this with the icon slot.
Shape
Avatars can be shaped using the shape attribute.
Avatar Groups
You can group avatars with a few lines of CSS.
API
Importing
If you're using the autoloader or a hosted project, components load on demand — no manual import needed. To cherry-pick this component, use one of the following snippets.
import '@cruglobal/cornerstone-components/components/avatar/avatar.js';
import './cornerstone/components/avatar/avatar.js';
import CsAvatar from '@cruglobal/cornerstone-components/react/avatar/index.js';
Slots
Learn more about using slots.
| Name | Description |
|---|---|
icon | The default icon to use when no image or initials are present. Works best with <cs-icon>. |
Attributes & Properties
Learn more about attributes and properties.
| Property | Attribute | Description | Type | Default | Reflects |
|---|---|---|---|---|---|
image | image | The image source to use for the avatar. | string | '' | — |
initials | initials | Initials to use as a fallback when no image is available (1-2 characters max recommended). | string | '' | — |
label | label | A label to use to describe the avatar to assistive devices. | string | '' | — |
loading | loading | Indicates how the browser should load the image. | 'eager' | 'lazy' | 'eager' | — |
shape | shape | The shape of the avatar. | 'circle' | 'square' | 'rounded' | 'circle' | Yes |
Events
Learn more about events.
| Name | Description |
|---|---|
cs-error | The image could not be loaded. This may because of an invalid URL, a temporary network condition, or some unknown cause. |
CSS Custom Properties
Learn more about CSS custom properties.
| Name | Description | Default |
|---|---|---|
--size | The size of the avatar. | — |
CSS Parts
Learn more about CSS parts.
| Name | Description | CSS selector |
|---|---|---|
icon | The container that wraps the avatar's icon. | ::part(icon) |
image | The avatar image. Only shown when the image attribute is set. | ::part(image) |
initials | The container that wraps the avatar's initials. | ::part(initials) |
Dependencies
This component automatically imports the following elements. Sub-dependencies, if any exist, are included in this list.