# Avatars

Photos and initials with badges and groups, cut out cleanly on any background.

Package: @reuse-sh/avatars

## Principles

These are the rules to keep when you adapt this library. The code is one way to keep them. An adaptation on any framework must keep every one.

- Cut, never paint. Badges and overlaps are masks through the image, so no painted ring fights the background.

- Keep initials underneath. Initials show until the image loads and stay if it fails.

- Name badges in words. The badge label joins the accessible name, and the drawing stays decorative.

- Treat text as text. Names, labels and icons go in as text or nodes and are never parsed as HTML.

- Size cutouts from the badge. Counts of two digits or more get a capsule cutout measured from the badge itself.

- Restore the host. Destroy puts back the original content, styles and listeners.

## Install

```bash
npm install @reuse-sh/avatars
```

## Integration notes

- The badge label is part of the accessible name. The badge drawing is decorative.

- Counts of two digits or more get a capsule cutout measured from the badge itself.

- Initials split on whole characters, so accents and emoji stay intact.

## API

- `enhanceAvatar(root)`: Adds cutouts and fallbacks to avatar markup already on the page. Returns refresh and destroy.

- `createAvatar(root, { name, src?, size?, badge? })`: Builds an avatar with initials, an image and an optional badge. Size is 40 by default.

- `badge`: { type: "dot" | "count" | "icon", label, corner? }. The label joins the accessible name.

- `createAvatarGroup(root, options?)`: Overlaps avatars and cuts each one where the next covers it. Options: overlap, 12 by default, and clearance, 2.

- `getInitials(name)`: Initials for a name, safe for emoji and accents.

- `Avatar, AvatarGroup`: The React components around the same code.

## Browser JavaScript

```js
import { enhanceAvatar, createAvatarGroup } from "@reuse-sh/avatars";
import "@reuse-sh/avatars/styles.css";

const avatar = enhanceAvatar(avatarElement);
const group = createAvatarGroup(groupElement, { overlap: 12 });
```

## React

```tsx
import { Avatar, AvatarGroup } from "@reuse-sh/avatars/react";
import "@reuse-sh/avatars/styles.css";

<AvatarGroup overlap={12}>
  <Avatar name="Alex Rivers" badge={{ type: "dot", label: "Online" }} />
  <Avatar name="Sam Field" badge={{
    type: "count", count: 128, label: "128 messages",
  }} />
</AvatarGroup>
```

## Agent workflow

1. Inspect the project and read the installed package's types and stylesheet.

2. Reuse the native controller. Use the React adapter only in a React surface.

3. Adapt styles and data connections to the project. Keep every principle above. Do not recreate the gesture or state engine.

4. Connect destroy and unsubscribe callbacks to the owner lifecycle.

5. Verify keyboard access, pointer/touch behavior, resize, empty/one-item states, errors, reduced motion, and teardown where applicable.

6. Report the actual checks and remaining browser/device limits.

## Source

https://github.com/reuse-sh/reuse/tree/main/packages/avatars/src

License: MIT for original library code. Preserve dependency and asset license notices.