Avatar
An image, initials, or icon that represents a user.
Usage
Basic
Loading demo...
Sizes
size takes a preset name or a custom pixel value.
Loading demo...
Text Avatars
Loading demo...
Icon Avatars
Loading demo...
Avatar Group
Avatars beyond max collapse into a +N avatar.
Loading demo...
Hover Effects
hoverEffect sets each avatar's hover feedback; spreadOnHover fans the row apart while the group is hovered.
Loading demo...
Overflow Popover
overflowPopover reveals the collapsed avatars from +N; the overflow slot replaces the panel content.
Loading demo...
Status
Loading demo...
Best Practices
- Pass
nameto generate identity marks instead of hard-coding initials. - Provide meaningful
altwhensrcshows a real user's image. - Use
statusfor presence only; useTxStatusBadgefor textual system state. - When a group shows
status, raiseoverlapor enablespreadOnHoverso dots stay visible. - Treat the overflow popover as glance-only; use a list component when members need actions.
API Reference
TxAvatar
Props
| Prop | Type | Default | Description |
|---|---|---|---|
src | string | - | Image URL; falls back when it fails to load. |
alt | string | - | Image alt text; provide it when src shows a real user. |
name | string | - | Name used to generate initials. |
icon | string | - | Fallback icon name, passed to TxIcon. |
size | 'small' | 'medium' | 'large' | 'xlarge' | number | \${number}` | `${number}px`` | 'medium' | Preset name or positive pixel size; invalid values are ignored. |
status | 'online' | 'offline' | 'busy' | 'away' | - | Status dot in the corner, inset to follow shape. |
shape | 'circle' | 'square' | 'rounded' | 'circle' | Avatar shape. |
clickable | boolean | false | Enables pointer styling, button semantics, and the click event. |
backgroundColor | string | - | Background of the fallback content. |
textColor | string | '#ffffff' when backgroundColor is set | Text color of the fallback content; applies only with backgroundColor. |
Events
| Event | Payload | Description |
|---|---|---|
click | - | Fires on click, Enter, or Space when clickable is set. |
Slots
| Slot | Props | Description |
|---|---|---|
default | - | Custom fallback content; takes priority over icon and name. |
TxAvatarGroup
Props
| Prop | Type | Default | Description |
|---|---|---|---|
max | number | child count | Avatars shown before collapsing into +N; negative values count as zero. |
size | AvatarSize | - | Injected into child avatars that don't set their own size. |
overlap | number | string | 8 | How far neighbouring avatars overlap; numbers are px. |
hoverEffect | 'none' | 'lift' | 'lift' | Per-avatar hover feedback; lift raises, shadows, and brings the avatar forward. |
spreadOnHover | boolean | false | Eases the overlap to spreadOverlap while the group is hovered. |
spreadOverlap | number | string | 0 | Overlap once spread; negative values leave a gap. |
overflowPopover | boolean | false | Attaches an overflow popover to +N. |
overflowPopoverTrigger | 'hover' | 'click' | 'hover' | How the popover opens. |
overflowPopoverPlacement | PopoverPlacement | 'top' | Popover position relative to +N. |
Slots
| Slot | Props | Description |
|---|---|---|
default | - | TxAvatar children or compatible avatar VNodes. |
overflow | { nodes: VNode[], count: number } | Overflow popover panel content; nodes are the avatars max cut off. |
Overview
- Content falls back from the image to the default slot,
icon, initials fromname, then the defaultusericon; a failed image load falls back the same way. - Initials are the first characters of the first and last words, uppercased.
- With
clickable, the root getsrole="button"andtabindex="0", and Enter / Space emitclicklike a click does. - In a group,
z-indexrises left to right, so each avatar covers the bottom-right corner — status dot included — of the one before;liftbrings the hovered avatar forward. - With
overflowPopoveron and avatars overflowing,+Nis wrapped inTxPopover; otherwise it is a plain avatar with no floating layer. - Under reduced motion, the hover translate and transitions drop out; the forward stacking and shadow remain.
Technologies
- The root doesn't clip; the image and fallback layers do, which lets the status dot extend past the shape.
- Group negative margins and
z-indexcome from the stylesheet (--tx-avatar-group-overlap,--tx-avatar-group-index); children only get their ring inline. - Source:
packages/tuffex/packages/components/src/avatar/.
查看源码
packages/tuffex/packages/components/src/avatar/index.ts
Customization
| Variable | Written by | Purpose |
|---|---|---|
--tx-avatar-size | custom size | Width and height. |
--tx-avatar-font-size | custom size | Fallback text and icon size. |
--tx-avatar-status-size | custom size | Status dot outer diameter, ring included. |
--tx-avatar-status-border | custom size | Status dot ring width. |
--tx-avatar-bg | backgroundColor | Fallback background. |
--tx-avatar-text | textColor (with backgroundColor) | Fallback text color. |
--tx-avatar-ring | caller / theme | Ring color around the status dot and grouped avatars; defaults to --tx-bg-color. |
--tx-avatar-group-overlap | overlap | Resolved overlap distance. |
--tx-avatar-group-spread-overlap | spreadOverlap | Overlap once spread. |
--tx-avatar-group-hover-z | caller / theme | z-index of the hovered avatar; defaults to 999. |
--tx-avatar-group-overflow-width | caller / theme | Overflow panel width before wrapping; defaults to 232px. |
--tx-avatar-group-border | caller / theme | Ring color of grouped avatars. |
--tx-avatar-*-preset, --tx-avatar-status-diameter, --tx-avatar-status-ring, --tx-avatar-status-inset, --tx-avatar-group-gap, --tx-avatar-group-index, and --tx-avatar-group-more-z are internal; don't set them directly.