# Avatar

> A round avatar with initials in a collaborator color. A native Pyzed component for Python desktop GUIs, with a live preview, code examples and its API.

Source: https://albakore.github.io/pyzed/library/avatar/

:::tip[In plain words]
A circle with someone's initials, in their own color.
:::

A circle with initials. `index` picks one of the theme's collaborator (player) colors, so the same person keeps the same color; `color` sets it directly.

`ui.avatar` · Category: [Display](https://albakore.github.io/pyzed/library/#display) · [Full reference →](https://albakore.github.io/pyzed/reference/ui/#avatar)

**Code:**

```python
pz.row([
    ui.avatar("AL", index=0),
    ui.avatar("KV", index=1),
    ui.avatar("MZ", index=2, size=28),
    ui.avatar("JD", index=3, size=36),
], spacing=8, align="center")
```

## When to use

- For the account in the title bar, comment authors or collaborators.
- For several people at once use [Facepile](https://albakore.github.io/pyzed/library/facepile/).

## Usage

```python
import pyzed as pz
from pyzed import ui

pz.row([
    ui.avatar("AL", index=0),
    ui.avatar("KV", index=1),
    ui.avatar("MZ", index=2, size=28),
    ui.avatar("JD", index=3, size=36),
], spacing=8, align="center")
```

## Variants

:::note[About these captures]
Each capture is recorded by pyzed itself, off-screen at 2x, in One Dark or One Light to match this site's theme, and cropped to the component so it shows at its real size. The pointer hovers, presses or types into it; a component that does not react to the pointer cycles through a few themes. With reduced motion you see the first frame. Open **Code** under a capture to see the snippet that draws it; free names such as `on_save` stand for your own callbacks.
:::

### Collaborator color

```python
ui.avatar("AL", index=0)
```

```python
ui.avatar("KV", index=1)
```

```python
ui.avatar("MZ", index=2)
```

```python
ui.avatar("JD", index=3)
```

```python
ui.avatar("SR", index=4)
```

```python
ui.avatar("PB", index=5)
```

### Size

```python
ui.avatar("KV", size=18)
```

```python
ui.avatar("KV", size=22)
```

```python
ui.avatar("KV", size=32)
```

```python
ui.avatar("KV", size=48)
```

### Color

```python
ui.avatar("PZ", color="#c678dd", size=32)
```

```python
ui.avatar("UI", color="#e5c07b", size=32)
```

### States and events

`image=` shows a picture instead of the initials and `tooltip=` names the person on hover.

```python
ui.avatar("KK", status="online", size=32)
```

```python
ui.avatar("AL", status="away", index=2, size=32)
```

```python
ui.avatar("MZ", status="busy", index=4, size=32)
```

## Events

Avatar has no events of its own: it shows what you give it. Like every widget it also has the **18 common events** (`click`, `double_click`, `right_click`, `mouse_enter`, `drag`, `key_down`, `resize`…), attached with `.on(...)`: see [Events](https://albakore.github.io/pyzed/guides/events/) and [Events of every component](https://albakore.github.io/pyzed/library/events/).

## Properties and API

### `ui.avatar`

```python
avatar(
    initials,
    *,
    color=None,
    size=22,
    index=0,
    image=None,
    status=None,
    tooltip=None,
    theme=None,
)
```

A round avatar with initials.

| Property | Default | Description |
| --- | --- | --- |
| `initials` | *required* | Initials (the first two are used). |
| `color` | `None` | Background color. |
| `size` | `22` | Diameter. |
| `index` | `0` | Picks a collaborator color from the theme (`theme.players`). |
| `image` | `None` | A picture (path or bytes) instead of the initials. |
| `status` | `None` | Presence dot: `"online"`, `"away"`, `"busy"`, `"offline"` or a color. |
| `tooltip` | `None` | Text shown on hover (the person's name). |
| `theme` | `None` | Theme to use instead of the current one (`pyzed.theme.current()`). |

[Full reference →](https://albakore.github.io/pyzed/reference/ui/#avatar)

## Related

- [Facepile](https://albakore.github.io/pyzed/library/facepile/): Overlapping collaborator avatars with +N.
- [Title bar](https://albakore.github.io/pyzed/library/title-bar/): The top bar with project and branch pickers.