---
title: "MazAvatar"
description: "MazAvatar is a standalone component that displays an image or an icon with a caption. It can be used to display a user's profile picture, a placeholder image, or an icon."
package: "maz-ui"
url: "https://maz-ui.com/components/maz-avatar"
---

# MazAvatar

> MazAvatar is a standalone component that displays an image or an icon with a caption. It can be used to display a user's profile picture, a placeholder image, or an icon.

- Package: `maz-ui`
- Import: `import MazAvatar from 'maz-ui/components/MazAvatar'`
- Nuxt: auto-imported by `@maz-ui/nuxt`, no import needed in a Nuxt app
- Web: https://maz-ui.com/components/maz-avatar

> Before use it, you should install the MazUi plugin in your project, follow instructions in [Getting Started](../guide/getting-started.md)

**Tip:**

This component uses [vLazyImg](../directives/lazy-img.md) directive

## Basic usage

```vue
<script lang="ts" setup>
import MazAvatar from 'maz-ui/components/MazAvatar'
</script>

<template>
  <MazAvatar src="https://api.dicebear.com/7.x/big-smile/svg?backgroundColor=1d90ff&scale=80" />
</template>
```

## Options

**Tip:**

See all the options props here

```vue
<script lang="ts" setup>
import MazAvatar from 'maz-ui/components/MazAvatar'
function clicked() { console.log('clicked') }
</script>

<template>
  <MazAvatar
    caption="Louis Mazel"
    size="1.5rem"
  />
  <MazAvatar
    src="https://api.dicebear.com/7.x/big-smile/svg?backgroundColor=1d90ff&scale=80&seed=maz-ui"
    size="2rem"
    href="https://api.dicebear.com/7.x/big-smile/svg?backgroundColor=1d90ff&scale=80&seed=maz-ui"
    target="_blank"
    rounded-size="none"
    clickable
  >
    <template #icon>
      <MazIcon icon="/eye.svg" />
    </template>
  </MazAvatar>
  <MazAvatar
    src="https://api.dicebear.com/7.x/big-smile/svg?backgroundColor=1d90ff&scale=80&seed=200"
    size="2.5rem"
    clickable
    rounded-size="xl"
    @click="clicked"
  />
  <MazAvatar
    src="https://api.dicebear.com/7.x/big-smile/svg?backgroundColor=1d90ff&scale=80&seed=600"
    size="3rem"
    bordered
  />
</template>
```

## Initials from caption

When no `src` is provided, `MazAvatar` displays initials generated from the `caption`. The `letter-count` prop (default `2`) controls how many letters are displayed:

- **Single word**: the first `letter-count` characters of the word are used.
- **Multiple words**: the first letter of each of the first `letter-count` words is used.

Initials are always uppercased.

```vue
<template>
  <!-- "AD" -->
  <MazAvatar caption="admin" />
  <!-- "ADM" -->
  <MazAvatar caption="admin" :letter-count="3" />
  <!-- "LM" -->
  <MazAvatar caption="Louis Mazel" />
  <!-- "JCD" -->
  <MazAvatar caption="Jean Claude Dus" :letter-count="3" />
</template>
```

## On Error

When no `src` (and no `caption`) is provided, or when the image fails to load, `MazAvatar` displays the default `no-image` placeholder.

```html
<MazAvatar @error="error" src="https://broken-link-image-src.example" />
```

## Fallback image loaded on error

```html
<MazAvatar
  src="https://broken-link-image-src.com"
  fallback-src="https://api.dicebear.com/7.x/big-smile/svg?backgroundColor=1d90ff&scale=80&seed=100"
/>
```

## Loading

The props `loading` has 3 possible values: `intersecting`, `lazy`, or `eager`.

By default, the value is `intersecting` which means the image will be loaded when it's intersecting with the `IntersectionObserver` browser API. This mode uses the [`MazLazyImg`](./maz-lazy-img.md) component with [`vLazyImg`](../directives/lazy-img.md) directive to handle the lazy loading.

Native modes:

- `lazy`: The image will be loaded only when it's in the viewport
- `eager`: The image will be loaded immediately

These modes are native use an `HTMLImageElement` with the `loading` attribute. (see [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#attr-loading)). **Useful for SSR (Server Side Rendering) or when you want to load the image immediately.**

```html
<MazAvatar
  loading="intersecting"
  src="https://api.dicebear.com/7.x/big-smile/svg?backgroundColor=1d90ff&scale=80&seed=123"
/>
<MazAvatar loading="lazy" src="https://api.dicebear.com/7.x/big-smile/svg?backgroundColor=1d90ff&scale=80&seed=123" />
<MazAvatar loading="eager" src="https://api.dicebear.com/7.x/big-smile/svg?backgroundColor=1d90ff&scale=80&seed=123" />
```

## Image height full

By default the image fills the avatar **width** (`width: 100%`). Enable `image-height-full` to make the image fill the **height** instead: it keeps its aspect ratio, fills 100% of the height and overflows/crops horizontally. This is ideal for wide images or SVGs (like flags) that must cover the whole avatar.

```vue
<template>
  <!-- default: width 100% -->
  <MazAvatar src="https://placedog.net/300/200" />
  <!-- height 100%, cropped on the sides -->
  <MazAvatar image-height-full src="https://placedog.net/300/200" />
</template>
```

## MazAvatar API

`import MazAvatar from 'maz-ui/components/MazAvatar'`

### Props

- `src` (`string | null`): The source of the image.
- `caption` (`string | null`): The caption of the avatar.
- `href` (`string`): The link of the avatar.
- `to` (`string | Record<string, unknown>`): The link (router-link or nuxt-link) of the avatar.
- `alt` (`string`, default: `"avatar image"`): The alt of the image.
- `target` (`string`, default: `"_self"`): The target of the link.
- `size` (`` `${number}rem` | `${number}px` | `${number}em` | `${number}vw` | `${number}vh` | `${number}vmin` | `${number}vmax` | `${number}%` | `${number}ch` | `${number}cm` | `${number}mm` | `${number}in` | `${number}ex` | `${number}pc` | `${number... ``): The size of the avatar - a keyword from `MazSize` or any CSS size unit. Values: `'mini'`, `'xs'`, `'sm'`, `'md'`, `'lg'`, `'xl'`, `'2rem'`, `'48px'` (non exhaustive).
- `bordered` (`boolean`): Add a border to the avatar.
- `clickable` (`boolean`): Make the avatar clickable.
- `square` (`boolean`): Make the avatar square.
- `no-elevation` (`boolean`): Remove the shadow.
- `show-caption` (`boolean`): Show the caption.
- `image-height-full` (`boolean`): Make the image height full.
- `hide-loader` (`boolean`): Remove the loader.
- `button-color` (`"primary" | "secondary" | "accent" | "info" | "success" | "warning" | "destructive" | "contrast" | "transparent"`, default: `"info"`): The color of the clickable button.
- `hide-clickable-icon` (`boolean`): Remove the icon on hover when component is clickable.
- `letter-count` (`number`, default: `2`): Number of letters to display in the round text initials. - For a single-word caption, the first `letterCount` characters are used (`'admin'` + `3` -> `'ADM'`). - For a multi-word caption, the first letter of the first `letterCount` words is used (`'Louis Mazel'` -> `'LM'`).
- `rounded-size` (`MazRoundedSize`): Size of the rounded. Values: `'none'`, `'sm'`, `'md'`, `'lg'`, `'xl'`, `'full'` (non exhaustive).
- `fallback-src` (`string`): The fallback src to replace the src on loading error.
- `loading` (`"intersecting" | "lazy" | "eager"`, default: `"intersecting"`): The loading strategy of the image - lazy, eager or intersecting.
- `color` (`"primary" | "secondary" | "accent" | "info" | "success" | "warning" | "destructive" | "contrast" | "transparent"`, default: `"primary"`): The color of the avatar.

### Events

- `@click` (payload: `event: MouseEvent`): Emitted when the avatar is clicked
- `@intersecting` (payload: `el: Element`): Emitted when the image is intersecting
- `@loading` (payload: `el: Element`): Emitted when the image is loading
- `@loaded` (payload: `el: Element`): Emitted when the image is loaded
- `@error` (payload: `el: Element`): Emitted when the image is in error

### Slots

- `#round-text`: Replace the initials displayed when a caption is set and no image source is provided
- `#icon`: The icon displayed on the clickable button overlay (shown on hover/focus)
- `#caption`: Replace the caption displayed below the avatar (requires `showCaption`)
