---
title: Avatar
url: "https://native-sdk.dev/docs/components/avatar"
docs_index: /llms.txt
lastUpdated: 2026-10-16
---

> For an index of all documentation, see [/llms.txt](/llms.txt).

Use `avatar` to display an image with an initials fallback. The element content supplies the initials, and `image` binds to a registered `ImageId`. Register bytes through `fx.registerImageBytes` in a Zig app or declare files in the app manifest’s `assets.images` list. Image ID `0` means no image, so keep that value until registration succeeds.

## Markup

```html
<row gap="12" cross="center">
  <avatar>ZN</avatar>
  <avatar>CT</avatar>
  <avatar image="{profile_image}" label="Profile picture">NS</avatar>
</row>
```

## Programmatic construction (Zig)

In a Zig view, the `canvas.Ui` builder constructs the same tree programmatically:

```zig
ui.avatar(.{}, "ZN")
```

With a registered image the engine clips it to the avatar circle (`cover` fit); the initials remain the fallback while the id is 0:

```zig
ui.avatar(.{ .image = image_id }, "ZN")
```

An avatar can select one region from a registered texture atlas by declaring all four source coordinates in decoded-image pixels. The same crop is `ElementOptions.image_src` in a Zig view:

```html
<avatar image="{atlas_image}" source-x="64" source-y="0"
  source-width="32" source-height="32" label="Profile picture">ZN</avatar>
```

## Attributes

| Attribute       | Description                                                                                                                                                                                                               |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `text`          | Text value for text-bearing elements; a literal or one \{binding}.                                                                                                                                                        |
| `image`         | avatar and image: one \{binding} to a u64 ImageId the app registered at runtime (Cmd.imageLoad, fx.loadImage, fx.registerImageBytes); 0 draws nothing (an avatar falls back to its initials). Required on the image leaf. |
| `source-x`      | avatar and image: left edge of an optional source crop, in decoded-image pixels. Declare all four source-\* attributes together beside image.                                                                             |
| `source-y`      | avatar and image: top edge of an optional source crop, in decoded-image pixels. Declare all four source-\* attributes together beside image.                                                                              |
| `source-width`  | avatar and image: width of an optional source crop, in decoded-image pixels. Declare all four source-\* attributes together beside image.                                                                                 |
| `source-height` | avatar and image: height of an optional source crop, in decoded-image pixels. Declare all four source-\* attributes together beside image.                                                                                |
| `label`         | Accessible name; when set it REPLACES the element's text as the announced name - screen readers and automation snapshots see the label, never the text it shadows.                                                        |

---

For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md)

For an index of all available documentation, see [/llms.txt](/llms.txt)

For agent-facing discovery, including API and MCP surfaces, see [/agents.md](/agents.md)