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.

Before use it, you should install the MazUi plugin in your project, follow instructions in Getting Started

TIP

This component uses vLazyImg directive

Basic usage

<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

LM

<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.

AD

ADM

LM

JCD

<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.

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

Fallback image loaded on error

<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 component with vLazyImg 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). Useful for SSR (Server Side Rendering) or when you want to load the image immediately.

<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.

<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>

Props

Name	Description	Type	Required	Default	Possible values
src	The source of the image	string | null	No	-	-
caption	The caption of the avatar	string | null	No	-	-
href	The link of the avatar	string	No	-	-
to	The link (router-link or nuxt-link) of the avatar	string | Record<string, unknown>	No	-	-
alt	The alt of the image	string	No	"avatar image"	-
target	The target of the link	string	No	"_self"	-
size	The size of the avatar - a keyword from MazSize or any CSS size unit	``${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...`	No	-	'mini' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2rem' | '48px'
bordered	Add a border to the avatar	boolean	No	-	-
clickable	Make the avatar clickable	boolean	No	-	-
square	Make the avatar square	boolean	No	-	-
no-elevation	Remove the shadow	boolean	No	-	-
show-caption	Show the caption	boolean	No	-	-
image-height-full	Make the image height full	boolean	No	-	-
hide-loader	Remove the loader	boolean	No	-	-
button-color	The color of the clickable button	"primary" | "secondary" | "accent" | "info" | "success" | "warning" | "destructive" | "contrast" | "transparent"	No	"info"	'primary' | 'secondary' | 'accent' | 'info' | 'success' | 'warning' | 'destructive' | 'contrast' | 'transparent'
hide-clickable-icon	Remove the icon on hover when component is clickable	boolean	No	-	-
letter-count	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').	number	No	2	-
rounded-size	Size of the rounded	MazRoundedSize	No	-	'none' | 'sm' | 'md' | 'lg' | 'xl' | 'full'
fallback-src	The fallback src to replace the src on loading error	string	No	-	-
loading	The loading strategy of the image - lazy, eager or intersecting	"intersecting" | "lazy" | "eager"	No	"intersecting"	'intersecting' | 'lazy' | 'eager'
color	The color of the avatar	"primary" | "secondary" | "accent" | "info" | "success" | "warning" | "destructive" | "contrast" | "transparent"	No	"primary"	'primary' | 'secondary' | 'accent' | 'info' | 'success' | 'warning' | 'destructive' | 'contrast' | 'transparent'

Events

Event name	Payload	Description
loading	el: Element	Emitted when the image is loading
click	event: MouseEvent	Emitted when the avatar is clicked
intersecting	el: Element	Emitted when the image is intersecting
loaded	el: Element	Emitted when the image is loaded
error	el: Element	Emitted when the image is in error

Slots

Name	Description	Bindings
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)	-