# Avatar
> Avatar with initials on a pixel field coloured from the name, a status dot that pulses when online and a hover ripple.
- React: `import { PxAvatar } from "@/components/lumesec/px-avatar"`
- Collection: Pixel UI (https://elements.lumesec.ai/components/pixel-ui)
- Registry item: https://elements.lumesec.ai/r/px-avatar.json
- Page: https://elements.lumesec.ai/components/pixel-ui/avatar



Live preview: https://elements.lumesec.ai/view/px-avatar

Demo source:

```tsx
import { PxAvatar } from "@/components/lumesec/px-avatar";

export default function PxAvatarDemo() {
  return (
    <div className="flex w-full max-w-[380px] flex-wrap items-center justify-center gap-2.5">
      <div className="flex">
        <PxAvatar name="Ada Lovelace" status="online" size={44} />
        <PxAvatar name="Grace Hopper" status="busy" size={44} className="-ml-[10px]" />
        <PxAvatar name="Alan Turing" status="away" size={44} className="-ml-[10px]" />
        <PxAvatar name="Katherine Johnson" status="offline" size={44} className="-ml-[10px]" />
      </div>
      <PxAvatar name="Marcus Z" shape="square" size={56} />
    </div>
  );
}
```

## Playground

Change a prop and the component re-renders. Props marked remounts set an initial value, so the component starts over.

## Installation

```bash
npx shadcn@latest add @lumesec/px-avatar
```

First time with the @lumesec registry? Register it once, or install by URL:

```bash
npx shadcn@latest registry add @lumesec=https://elements.lumesec.ai/r/{name}.json
npx shadcn@latest add https://elements.lumesec.ai/r/px-avatar.json
```

## Usage

React:

```tsx
import { PxAvatar } from "@/components/lumesec/px-avatar";

export function Example() {
  return <PxAvatar name="Ada Lovelace" status="online" size={44} />;
}
```

## Behaviour

Initials on a pixel field coloured from the name, so the same person always gets the same colour. Status dots pulse when online, and hovering sends a ripple through the field.

## API reference

### Props

Also accepts every prop of `<span>` (`React.ComponentProps<"span">`), spread onto the root element.

| Prop     | Type                                        | Default    | Description                                                                           |
| -------- | ------------------------------------------- | ---------- | ------------------------------------------------------------------------------------- |
| `name`   | `string`                                    | `"Guest"`  | Source of the initials (first letters of the first two words) and of the colour.      |
| `size`   | `number`                                    | `40`       | Size of the avatar in pixels. The canvas is 6px larger, so the online pulse has room. |
| `status` | `"online" \| "away" \| "busy" \| "offline"` | —          | Adds a coloured dot in the lower right corner; `online` pulses.                       |
| `shape`  | `"circle" \| "square"`                      | `"circle"` | `square` gives rounded-square corners.                                                |

### Ref

`ref` points at the root `HTMLSpanElement`.

## Accessibility

* The root has `role="img"` and an `aria-label` with the name, or the name and status, for example "Ada Lovelace, online".
* The canvas and the initials are `aria-hidden`, so the label is read once.
* Reduced motion: the online pulse and the hover ripple are off.

## Theming

Styled with Tailwind classes on your shadcn theme tokens, so light and dark follow your theme. The accent comes from `--lumesec`. See [Theming](/docs/theming).

This component reads `--foreground`, `--card`, `--muted-foreground`, `--lumesec-success`, `--lumesec-warning` and `--destructive`.

## Notes

* The hue is a hash of `name`, so the same name always gets the same colour in a given theme.
* Initials are text in the inherited sans font, sized to the avatar (36% of `size` for two letters, 42% for one), so accented letters render too. They are white, or black on light colours, whichever contrasts more.
* Overlap avatars in a stack with a negative margin, for example `className="-ml-[10px]"` on every avatar after the first.