Avatar
Image, initials or icon for a person, with status dot and badge.
c2-avatar
Shows a person or entity as an image, initials or any slotted content, with an optional status dot or badge.
Resolution order: the src image (falling back to initials if it fails to load), then slotted content, then the
initials computed from name. Set auto-color to derive a stable background hue from the name.
Attributes
| Name | Type | Default | Description |
|---|---|---|---|
name | string | — | Full name: source of the initials, the accessible label and the auto-color hue. |
initial-count | number | 1 | Number of initials to show. With 2 and a name of three or more words, the first and last word are used. |
initials | string | undefined | undefined | Explicit initials; overrides the ones computed from name. |
src | string | undefined | undefined | Image URL. Falls back to the initials when the image fails to load. |
alt | string | undefined | undefined | Image alt text; defaults to name. |
auto-color | boolean | false | Derive a stable background hue from name (same name, same color). |
status | AvatarStatus | undefined | undefined | Presence dot in the bottom-right corner. |
editable | boolean | false | Allows the avatar to open an image picker and exposes a remove action for the current image. |
disabled | boolean | false | Disables editable avatar actions. |
accept | string | image/* | Accepted image MIME types or file extensions, using native file-input syntax. |
max-size | number | 0 | Maximum accepted image size in bytes. Zero means unlimited. |
Slots
| Name | Description |
|---|---|
(default) | Custom content shown instead of the initials (an icon, an emoji, an <img>). |
badge | Small element pinned to the bottom-right corner (a count, an icon). Replaces the status dot. |
edit-icon | Icon shown over an editable avatar. Defaults to a camera. |
remove-icon | Icon shown in the remove action. Defaults to a close mark. |
Events
| Name | Type | Description |
|---|---|---|
avatar-remove | CustomEvent<AvatarRemoveDetail> | Fired after the current local preview or src image is removed. |
error | Event | Fired when the src image fails to load; the initials are shown instead. |
file-reject | CustomEvent<AvatarFileRejection> | Fired when an editable avatar rejects a file by type or size. |
avatar-change | CustomEvent<AvatarChangeDetail> | Fired after an editable avatar accepts a local image. Upload detail.file and use detail.previewUrl for the immediate preview. |
CSS custom properties
Grouped by semantic target and state from --c2-<component>__<target>__<state>--<property>. Click a group to collapse it; click a name to copy it.
| Name | Type | Default | Description |
|---|---|---|---|
--c2-avatar--size | pixel | 32px | |
--c2-avatar--width | pixel | — | Falls back to --c2-avatar--size. |
--c2-avatar--height | pixel | — | Falls back to --c2-avatar--size. |
--c2-avatar--color | color | #ffffff | |
--c2-avatar--background | background | rgb(0, 122, 77) | Ignored when auto-color is set. |
--c2-avatar--box-shadow | box-shadow | — | e.g. 0 0 0 2px #fff for a ring in stacked groups. |
--c2-avatar--border-top-left-radius | border-radius | 999px | |
--c2-avatar--border-top-right-radius | border-radius | 999px | |
--c2-avatar--border-bottom-left-radius | border-radius | 999px | |
--c2-avatar--border-bottom-right-radius | border-radius | 999px | |
--c2-avatar--border-top | border | — | |
--c2-avatar--border-bottom | border | — | |
--c2-avatar--border-right | border | — | |
--c2-avatar--border-left | border | — | |
--c2-avatar--font-size | font-size | calc(var(--c2-avatar--size) * 0.4) | |
--c2-avatar--font-weight | font-weight | 600 | |
--c2-avatar--font-style | font-style | — | |
--c2-avatar--font-family | font-family | — | |
--c2-avatar--letter-spacing | letter-spacing | 0.02em | |
--c2-avatar__auto-color--saturation | saturation | 55% | Saturation of the hue derived from the name. |
--c2-avatar__auto-color--lightness | lightness | 30% | Lightness of the hue derived from the name. At the default saturation every hue keeps white initials at 4.5:1 or better. |
--c2-avatar__image--object-fit | object-fit | cover | |
--c2-avatar__editor--background | color | rgba(0, 0, 0, 0.5) | |
--c2-avatar__editor--color | color | #ffffff | |
--c2-avatar__editor__focus--outline | outline | 2px solid rgba(2, 101, 220, 0.45) | |
--c2-avatar__editor__focus--outline-offset | pixel | 2px | |
--c2-avatar__editor-icon--size | pixel | 18px | |
--c2-avatar__remove--size | pixel | 22px | |
--c2-avatar__remove--background | color | #ffffff | |
--c2-avatar__remove--color | color | #52525b | |
--c2-avatar__remove--border | border | 1px solid #e4e4e7 | |
--c2-avatar__remove--box-shadow | box-shadow | 0 1px 3px rgba(0, 0, 0, 0.18) | |
--c2-avatar__badge--size | pixel | 10px | Diameter of the status dot; slotted badges size themselves. |
--c2-avatar__badge--border | border | 2px solid #ffffff | Ring separating the badge from the avatar. |
--c2-avatar__badge--offset | pixel | 0px | Positive values push the badge outwards. |
--c2-avatar__badge__online--color | color | rgb(34, 197, 94) | |
--c2-avatar__badge__away--color | color | rgb(245, 158, 11) | |
--c2-avatar__badge__busy--color | color | rgb(239, 68, 68) | |
--c2-avatar__badge__offline--color | color | rgb(161, 161, 170) | |
c2-avatar-group
Responsive stack of c2-avatar elements. It observes its rendered width and each avatar's actual size, then hides
the avatars that no longer fit and replaces them with a count. The host fills the available inline space up to
--c2-avatar-group--max-width, so it also reacts when its parent becomes narrower.
A hidden avatar is never marked with an attribute: it matches the custom state c2-avatar:state(group-hidden),
so neither the group's host nor the avatars the page rendered ever differ from the server's markup.
Attributes
| Name | Type | Default | Description |
|---|---|---|---|
max-visible | number | 0 | Optional hard cap in addition to the automatically calculated responsive limit. Zero means no hard cap. |
count-mode | AvatarGroupCountMode | hidden | Whether the overflow indicator shows +hidden or the total number of avatars. |
aria-label | string | Avatar group | Accessible name for the group. |
Slots
| Name | Description |
|---|---|
(default) | c2-avatar elements displayed in source order. |
Events
| Name | Type | Description |
|---|---|---|
overflow-change | CustomEvent<AvatarGroupOverflowDetail> | Fired when resizing changes the visible or hidden counts. |
CSS parts
Shadow DOM styling hooks used with ::part(name). Prefer CSS custom properties when they cover the change.
| Name | Description |
|---|---|
overflow | Count shown after the visible avatars. |
CSS custom properties
Grouped by semantic target and state from --c2-<component>__<target>__<state>--<property>. Click a group to collapse it; click a name to copy it.
| Name | Type | Default | Description |
|---|---|---|---|
--c2-avatar-group--max-width | pixel | 320px | Maximum responsive width of the group. |
--c2-avatar-group--overlap | pixel | 10px | Amount that adjacent avatars overlap. |
--c2-avatar-group__avatar--box-shadow | box-shadow | 0 0 0 2px #ffffff | Ring applied to slotted avatars so overlaps stay distinct. |
--c2-avatar-group__overflow--size | pixel | 32px | Width and height of the overflow count. |
--c2-avatar-group__overflow--background | color | #52525b | Overflow count background. |
--c2-avatar-group__overflow--color | color | #ffffff | Overflow count text colour. |
--c2-avatar-group__overflow--border | border | 2px solid #ffffff | Ring around the overflow count. |
--c2-avatar-group__overflow--border-radius | border-radius | 999px | Overflow count corner radius. |
--c2-avatar-group__overflow--font-size | font-size | 12px | Overflow count text size. |
--c2-avatar-group__overflow--font-weight | font-weight | 600 | Overflow count text weight. |