vue3-avatar

A user avatar component for vue3. By default it uses light colors for Background and dark colors for Text.

This component is highly inspired from vue-avatar.

This component computes the Initials from provided name with following rules:

1. Splits the name by spaces and hyphens.
2. Finds the first letter of each parts.
3. Maximum length of Avatar letters is 3.
4. If the name is splitted into more than 2 parts then picks the first letter of part1, part2 and last part.

This component can now also show an image by setting the imageSrc prop. If an error occurs in fetching the image from the provided source, the component falls back to Initials.

Examples

• Tony will become T
• Tony Stark will become TS
• Tony Howard-Stark will become THS
• Albert Tony Howard Stark will become ATS

Previews

Shapes & Base Styles

Status & Presence

PixelGen Themes

Auto-Contrast & Images

Interactive Avatar Groups

Installation

npm install vue3-avatar

Usage

vue3-avatar is very easy to use.

ES6

For Local Registration

import { Avatar, AvatarGroup } from "vue3-avatar";

export default {
  // ...
  components: {
    Avatar,
    AvatarGroup, // Optional: if you want to use grouping
    // ...
  },
  // ...
};

For Global Registration (with optional defaults)

Update main.js

import { createApp } from "vue";
import App from "./App.vue";
import Avatar from "vue3-avatar";

const app = createApp(App);

// Configure global defaults (Optional)
app.use(Avatar, {
  defaults: {
    size: 50,
    autoContrast: true,
    transition: true,
    loading: "lazy",
    shape: "circle",
  },
});

After importing the component, you can use it in your templates as:

<avatar name="John Doe"></avatar>

Nuxt.js Support

vue3-avatar v4.1 is fully SSR-safe and optimized for Nuxt.js 3+.

1. Installation in Nuxt

Create a plugin file plugins/avatar.ts:

import { defineNuxtPlugin } from "#app";
import Avatar from "vue3-avatar";

export default defineNuxtPlugin((nuxtApp) => {
  nuxtApp.vueApp.use(Avatar, {
    defaults: {
      size: 40,
      autoContrast: true,
    },
  });
});

2. Standard Scoped Slot for NuxtImg

Use the #image slot to integrate with custom image components like <NuxtImg> for better performance and automatic optimization.

<template>
  <Avatar name="John Doe" image-src="/profile.jpg">
    <template #image="{ src, alt, size, style }">
      <NuxtImg
        :src="src"
        :alt="alt"
        :width="size"
        :height="size"
        :style="style"
        loading="lazy"
      />
    </template>
  </Avatar>
</template>

3. SSR-Safe Deterministic Colors

Colors and Pixel patterns are generated deterministically based on the name prop, ensuring no hydration mismatches between server-side rendering and client-side activation.

Props

Events

Slots

CSS Variables

The component exposes CSS variables on the root element for easier theming:

--va-size
--va-bg
--va-color
--va-border-color
--va-radius
--va-clip-path
--va-font-size

AvatarGroup (New in v4)

You can group multiple avatars together with AvatarGroup.

<AvatarGroup :max="3">
  <Avatar name="Tony Stark" />
  <Avatar name="Bruce Banner" />
  <Avatar name="Steve Rogers" />
  <Avatar name="Natasha Romanoff" />
</AvatarGroup>

Props:

• max: (Number) Maximum number of avatars to show. Overflow is shown as +N.
• overlap: (Number) Overlap size in pixels (default 10).
• borderColor: (String) Border color for separators (default 'white').
• size: (Number) Size for the overflow badge (default 40).
• layout: (String) Layout of the avatars.
  • stack (default): Horizontal overlapping stack.
  • triangle: Pyramid shape where the first avatar is on top, and subsequent avatars form the base. Note: Triangle layout is limited to 3 items (2 visible + 1 overflow badge if needed).
• onClick: (Function) Click callback for the entire group.
• pointer: (Boolean) If true, applies pointer cursor to the group.

Events:

Tooltips:

• Hovering the group background shows all member names.
• Hovering the overflow badge (+N) shows only the hidden member names.
• Individual avatars show their own name on hover.

You can also pass props to individual Avatar components within the group. For example, you can set the status of each avatar.

<AvatarGroup :max="3">
  <Avatar name="Tony Stark" status="online" />
  <Avatar name="Bruce Banner" status="away" />
  <Avatar name="Steve Rogers" status="offline" />
  <Avatar name="Natasha Romanoff" />
</AvatarGroup>

Accessibility

v4.0.0 focuses heavily on accessibility:

• Roles: Renders as role="img" by default, or role="button" if interactive is true.
• Labels: Automatically generates aria-labels from alt or name props.
• Keyboard: When interactive is true, supports Tab navigation and Enter/Space activation.
• Status: Status text is included in the accessible label (e.g., "Avatar of John Doe. User is online").

Color Systems

vue3-avatar supports two color systems:

Default Colors (Modern)

By default, the component uses a modern color palette with light colors for text and dark colors for backgrounds. This provides better contrast and readability.

<avatar name="John Doe" />

Legacy Colors (vue-avatar compatible)

@deprecated For backwards compatibility with the original vue-avatar component, you can enable the legacy color palette by setting useLegacyColors to true. This uses the original 18-color palette from vue-avatar.

<avatar name="John Doe" :use-legacy-colors="true" />

Migration Guide (v4.0 -> v4.1)

v4.1 is fully backward compatible. Summary of new features:

1. PixelGen: Choose variant="pixel" for deterministic pixel art. Themes: earth, neon, ocean, forest, sunset, midnight, candy, retro.
2. Auto-Contrast: Set :auto-contrast="true" to automatically pick black/white text based on background.
3. Global Config: Pass defaults object to app.use(Avatar, { defaults: { ... } }).
4. Framework Ready: Use the #image slot for NuxtImg or other custom image loading scenarios.
5. Interactive Groups: Hear when the overflow badge is clicked with @overflow-click.

Migration Guide (v3 -> v4)

v4 is mostly backward compatible. Key changes:

1. Deprecated: useLegacyColors triggers a console warning.
2. Removed: inverted prop is removed. The default theme is now light. Use the dark prop to enable the dark theme.
3. Accessibility: The DOM structure has role attributes and improved labels. Ensure your tests don't rely on specific internal DOM structure if not needed.
4. Strict Initials: The initials algorithm is now frozen and formalized.

Developer Notes

This package is built with the node v16.20.2 (npm v8.19.4)

Creator

Mohammad Dilshad Alam created and maintains this component.