# Avatar

- Page: https://jiguang132.com/resources/astryx/docs/avatar
- Resource: Astryx (https://jiguang132.com/resources/astryx.md)
- All guides: https://jiguang132.com/resources/astryx/docs.md

Avatar represents a person or team with a profile photo, initials, or a default icon. Use it in comment headers, contact lists, chat messages, user cards, and anywhere you need to identify someone visually.

## Installation

```bash
npm install @astryxdesign/core@0.7.1 @astryxdesign/theme-neutral@0.7.1 @stylexjs/stylex@0.19.0
```

Requires React 19+, base CSS and a Theme provider. See [Setup](/resources/astryx/docs/getting-started).

## Avatar

Avatar represents a person or team with a profile photo, initials, or a default icon. Use it in comment headers, contact lists, chat messages, user cards, and anywhere you need to identify someone visually.

| Prop | Type | Default | Description |
|---|---|---|---|
| src | string |  | Primary image source URL. |
| fallbackSrc | string |  | Fallback image when primary fails. |
| name | string |  | User name for initials and alt text. |
| alt | string |  | Alt text (falls back to name). |
| size | 'xsm' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| number | 'md' | Avatar size. Use a named size ('xsm' 20px, 'sm' 24px, 'md' 36px, 'lg' 48px, 'xl' 128px) or a numeric pixel value. Avatar shares Icon's abbreviated scale, but its tiers are larger because avatars align with media rather than glyphs. Inside an AvatarGroup the group's size wins and this prop is ignored. |
| shape | 'circle' \| 'rounded' \| 'square' | 'circle' | Shape variant of the avatar. 'circle' (default) stays fully round. 'rounded' uses the element radius token so it matches UI corner rounding and can be set globally via theme. 'square' has no radius. Status dot positioning adapts automatically: 4-o'clock on circle, bottom-right corner on rounded/square. |
| status | ReactNode |  | Corner content for status indicators. AvatarStatusDot reports its `label` to the avatar, which composes it into the accessible name (e.g. "Jane Doe, Online") so screen readers announce the status. Reporting goes through context, so it still works when the dot sits inside a wrapper component of your own. |
| tooltip | string \| boolean | true | Tooltip shown on hover and keyboard focus. Omitted or true shows the avatar's name; a string shows that text instead; false shows no tooltip. Not auto-disabled when wrapped in your own Tooltip/HoverCard. Set tooltip={false} if you supply your own overlay. No tooltip is shown when tooltip is true/omitted and there is no name. |
| href | string |  | When set, the avatar renders as an interactive link (`<a>` or a custom link component) pointing here. This follows the same element-swap rule as Button. Requires a meaningful accessible name via `alt` or `name`: an interactive avatar without one warns in development. Inside an AvatarGroup, interactive avatars share a single Tab stop and are reached with arrow keys. |
| as | ElementType |  | Custom link component used when `href` is set (e.g. `next/link`). Overrides the provider-level LinkProvider default. Only applies with `href`. |
| target | string |  | Link target attribute. Only applies with `href`. |
| rel | string |  | Link rel attribute. Only applies with `href`. |
| onClick | (e: MouseEvent) => void |  | Click handler. When set without `href`, the avatar renders as a focusable `<button type="button">`. Requires a meaningful accessible name via `alt` or `name`: an interactive avatar without one warns in development. |

### Usage guidance

- Always pass a name so the avatar can show initials if the photo fails to load, and so screen readers can announce who it represents.
- Pick a size that matches the context: xsm or sm for inline mentions, md or lg for lists and cards, xl for profile headers.
- Add a status dot when knowing someone's availability matters, like in chat or team views.
- When wrapping an Avatar in your own Tooltip or HoverCard, set tooltip={false} so the built-in name tooltip does not overlap yours.
- Give every interactive avatar (href or onClick) a name or alt. It is the control's accessible name, and it warns in development when it is missing.
- Avoid: Rely on a status label to name an interactive avatar. "Online" says nothing about where the link goes.
- Avoid: Use Avatar for logos, product images, or anything that isn't a person or team. Use an image or icon instead.
- Avoid: Use xstyle or className to override shape. Use the shape prop instead so themes can control it globally.

### Theming API

```json
{
  "targets": [
    {
      "className": "astryx-avatar",
      "visualProps": [
        "size",
        "shape"
      ]
    },
    {
      "className": "astryx-avatar-fallback",
      "visualProps": [
        "size"
      ]
    },
    {
      "className": "astryx-avatar-status-dot",
      "visualProps": [
        "variant"
      ]
    },
    {
      "className": "astryx-avatar-status-dot-glyph",
      "visualProps": [
        "shape"
      ]
    }
  ],
  "vars": [
    {
      "name": "--_avatar-group-overlap",
      "description": "Negative inline offset applied to every avatar stacked in an AvatarGroup; the group pads its start edge by the same amount so the first avatar stays inside it. Set from the group size; a more negative value tightens the stack.",
      "default": "set at runtime from the group avatar size (px)",
      "private": true
    },
    {
      "name": "--_avatar-radius",
      "description": "Border radius of the avatar wrapper, content, focus ring, and the AvatarGroupOverflow \"+N\" chip. Set per shape variant by shapeStyles.",
      "default": "var(--radius-full)",
      "private": true
    }
  ],
  "derived": [
    {
      "property": "borderRadius",
      "vars": [
        "--_avatar-radius"
      ]
    }
  ]
}
```

## AvatarStatusDot



### Anatomy

- **Photo**: The profile image, loaded from the src URL. Shown when available.
- **Initials**: The first letter, digit or emoji of the first and last words of the name; punctuation is skipped. Shown when no photo is available. A name with no letters, digits or emoji shows the default icon instead.
- **Default icon**: A generic person silhouette. Shown when there is no photo or name.
- **Status dot**: A small indicator in the bottom-right corner showing availability (online, away, busy). Each variant pairs colour with a distinct shape so status does not rely on colour alone.

## Avatar Status Dot

Size-aware status indicator dot that reads avatar size from context and scales proportionally. Each variant pairs a colour with a distinct built-in shape (filled, ring, minus) so status is never conveyed by colour alone (WCAG 1.4.1).

| Prop | Type | Default | Description |
|---|---|---|---|
| variant | 'success' \| 'neutral' \| 'error' | 'success' | Semantic variant pairing colour with a distinct shape: success = filled green dot, neutral = grey ring, error = red dot with a minus bar. |
| label | string |  | Accessible label describing the status. Inside an Avatar it is composed into the avatar's accessible name (e.g. "Jane Doe, Online"); the Avatar root is role="img", which prunes child semantics, so the composed name is how the status reaches assistive tech. Standalone dots expose role="img" with this label directly. |
| icon | ReactNode |  | Icon centered inside the dot (hidden at tiny sizes). A rendered icon replaces the built-in shape glyph, so use a different icon per status. |


## Examples

- Avatar: Avatars at every size with an image, initials fallback, and a status dot. A quick visual reference for choosing the right size.
- Avatar Status Dot: AvatarStatusDot renders a presence indicator on an Avatar, with variants for positive, neutral, and negative states. The dot size automatically coordinates with the Avatar size.
- Avatar — Fallback Chain: Demonstrates the avatar fallback chain: primary image, fallback image, initials, then default icon.
- Avatar — Initials: Show initials instead of a photo. The avatar extracts the first and last initials from the name automatically. Use when you only have a user name, like in anonymous accounts or new user onboarding.
- Avatar — Interactive: Make an avatar interactive by passing `href` to render it as a link or `onClick` to render it as a button. Both forms are focusable and show a focus-visible ring for keyboard users. Use for profile links, mention pop-ups, or any avatar people can act on.
- AvatarStatusDot — Variants: Presence dots on Avatars using the success, neutral, and error variants. Pass an AvatarStatusDot to the Avatar status prop; the dot sizes itself to match the Avatar.
- Avatar — Tooltip: By default an avatar shows its name in a tooltip on hover and keyboard focus. Pass a string to show custom text instead, or false to turn the tooltip off.
- Avatar — User Card: Place an avatar next to a name and role to create a user card row. Use for comment headers, contact lists, profile sections, or anywhere you need to identify a person at a glance.
- Avatar — Photo: Show a profile photo at different sizes. Use when you have a user photo URL. If the image fails to load, initials are shown instead.
- Avatar — Status Dot: Add a status dot to an avatar to show whether someone is online, away, or busy. Use in chat, messaging, or any UI where knowing availability matters.

---

Index of all JGuang resources: https://jiguang132.com/llms.txt