vue3-avatar

vue3-avatar

A lightweight, customizable, and accessible avatar component for Vue 3 and Nuxt.

📖 Read the Documentation & Try the Interactive Playground

🆕 v5 is out — a real tooltip engine, badges, image fallback chains, as/disabled/selected/editable, and a TypeScript source. What's new · Migrating from v4

Avatar Vue is a feature-rich component for displaying user profiles, team members, or entity icons. It supports initials-based avatars, custom images with lazy loading, deterministic pixel art (identicons), and avatar groups with overflow handling.

Whether you need a simple profile picture or a complex team display, Avatar Vue handles fallback logic, accessibility, and responsiveness out of the box.

Why vue3-avatar?

Most UI libraries include an avatar, but only as a primitive — a circle, maybe an image. vue3-avatar is the choice when you need more without adding a full design system:

Works with Tailwind CSS, UnoCSS, Headless UI, or any setup that doesn't include a UI library. Drop it in and it handles the rest.

Key Features

• ⚡ Lightweight & Fast: Optimized for Vue 3.
• 🎨 Smart Initials: Automatically extracts Unicode-safe initials from names (e.g., "Tony Stark" → "TS") without splitting emoji or combining accents.
• 🖼️ Image Support: Seamlessly handles image URLs with automatic fallback to initials or pixel art on error.
• 👾 PixelGen: Generates consistent, deterministic pixel art (identicons) like GitHub/Gravatar.
• 👥 Avatar Groups: Easily stack avatars for teams with +N overflow badges.
• 🌗 Auto-Contrast: Automatically adjusts text color (black/white) based on background luminance.
• ♿ Accessible: Built with a11y in mind (ARIA roles, keyboard support).
• 🟢 Status Indicators: Built-in presence dots with custom statuses, sizes, colours, and an optional pulse.
• 💬 Built-in Tooltips: Styled, collision-aware tooltips with twelve placements — no Popper or Floating UI dependency.
• 🔴 Notification Badges: Counts, dots, and custom badge content in any corner.
• 🛡️ Resilient Images: Ordered fallback chains, a loading skeleton, and retina srcset support.
• ☁️ SSR & Nuxt Ready: Safe for server-side rendering with no hydration mismatches.

Examples

• Tony will become T
• Tony Stark will become TS
• Tony Howard-Stark will become THS
• Albert Tony Howard Stark will become ATS
• 👩‍💻 Ada keeps the joined emoji intact as 👩‍💻A

Previews

Shapes & Base Styles

Status & Presence

PixelGen Themes

Auto-Contrast & Images

Interactive Avatar Groups

Installation

npm install vue3-avatar

Usage

Avatar Vue 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, use it in your template:

<Avatar name="John Doe" />

An explicitly passed prop always wins over the app default, including a value that matches the component default or an explicit false:

<Avatar name="Ada Lovelace" :size="40" :auto-contrast="false" />

Nuxt.js Support

Avatar Vue is fully SSR-safe and optimized for Nuxt.js 3+, and ships an official Nuxt module.

1. Installation in Nuxt (recommended: Nuxt module)

Add vue3-avatar/nuxt to your modules array — <Avatar> and <AvatarGroup> are then auto-imported, no manual plugin registration needed:

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ["vue3-avatar/nuxt"],
  vue3Avatar: {
    defaults: {
      size: 40,
      autoContrast: true,
    },
  },
});

<template>
  <Avatar name="John Doe" />
</template>

See the full Nuxt module guide for all module options.

Manual plugin registration (fallback)

If you'd rather register the plugin yourself — or are using Vue 3 without 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, srcset, sizes, alt, size, style, class: imageClass, onLoad, onError }">
      <NuxtImg
        :src="src"
        :srcset="srcset"
        :sizes="sizes"
        :alt="alt"
        :width="size"
        :height="size"
        :style="style"
        :class="imageClass"
        @load="onLoad"
        @error="onError"
        loading="lazy"
      />
    </template>
  </Avatar>
</template>

3. SSR-Safe Deterministic Colors

Colors and pixel patterns are generated deterministically from name, or from the optional seed prop when supplied. Use the same value on the server and client. Pass a stable user ID to preserve generated colors and artwork after a rename; initials, tooltips, and accessible labels still follow name:

<Avatar :name="user.displayName" :seed="user.id" variant="pixel" />

Omitting seed preserves existing output. Seeds accept strings and numbers, including 0 and an empty string. Different seeds can still produce the same colors or pattern.

Props

Tooltip props

Full reference in the tooltip documentation.

Status props

Badge props

Badge content is capped so a corner marker stays one: counts above badgeMax render as 999+, and other content is trimmed to badgeMaxLength letters — the same three-character budget the initials use. The badge is also capped at the avatar's own width, so a long label cannot run across the face.

Image props

Interaction 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
--va-status-color
--va-status-size
--va-badge-bg
--va-badge-color

These are read by the component and can be set by you:

--va-focus-ring          /* focus outline colour */
--va-ring-color          /* ring shown when `selected` */
--va-skeleton-bg
--va-skeleton-shimmer
--va-edit-overlay-bg
--va-edit-overlay-color
--va-tooltip-bg
--va-tooltip-color
--va-tooltip-radius
--va-tooltip-font-size
--va-tooltip-padding
--va-tooltip-shadow
--va-tooltip-z-index

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.

Stack overlap and triangle edge placement follow the surrounding dir (ltr or rtl). When onClick is provided, only activation on the group root invokes the group callback; child avatars and the +N overflow badge retain their own interactions.

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

• Roles: Renders as role="img" by default, or role="button" if interactive is true. Use as="button" or as="a" to get real native semantics instead.
• Labels: Automatically generates aria-labels from alt or name props.
• Keyboard: When interactive is true, supports Tab navigation and Enter/Space activation. A focus ring is shown on :focus-visible, styleable through --va-focus-ring.
• Status: Status text is included in the accessible label (e.g., "Avatar of John Doe. User is online"), or replaced entirely by statusLabel.
• Badges: The badge is aria-hidden and its meaning is folded into the avatar's label, so it is announced once rather than twice.
• Tooltips: Rendered as role="tooltip" and referenced with aria-describedby only when they say something the label does not. Escape closes an open tooltip.
• Motion: The image fade, status pulse, skeleton shimmer and tooltip transition are all disabled under prefers-reduced-motion: reduce.

Color Systems

Avatar Vue 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 -> v5)

v5 has two breaking changes:

1. The native title attribute is gone. A styled tooltip replaces it. Set native-title to restore the old attribute, or :tooltip="false" for neither.
2. Status colours and positioning changed. CSS keywords became hexadecimal tokens, and the indicator is inset to sit on the avatar's outline.

The full migration guide covers both, with the code needed to pin the old behaviour.

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

The source is TypeScript throughout — utilities, composables, and SFCs using <script setup lang="ts">. The shipped declarations in dist/types are emitted from source by vue-tsc, so the public API cannot drift from the implementation. src/types.ts holds the exported type surface.

Node version

The published package is browser code and imposes no Node version of its own. The toolchain does: Vitest 4 needs ^20 || ^22 || >=24 and Vite needs ^20.19 || >=22.12. On Node 18 Vitest does not fail with a version error — it hangs at the RUN banner indefinitely. Develop and run CI on Node 20 or later.

Scripts

VS Code users get the same entries in the Run and Debug panel.

Visual regression testing

tests/visual/ renders the real components in a real browser, screenshots them, and compares against committed reference images pixel by pixel — plus direct colour probes that assert the documented status, badge, and tooltip palettes are painted exactly. jsdom cannot do this: it has no layout engine, so it cannot tell you a status dot drifted off a hexagon's edge or that a tooltip flipped to the wrong side.

232 reference images cover shape x variant, status x corner x shape, badge variant x corner, all eight pixel themes, all twelve tooltip placements, group layouts, and interaction states. Boolean props are covered pairwise in tests/permutations.spec.ts, where they are far cheaper to run than as images.

See tests/visual/README.md for the details, including how to add a Linux golden set for CI.

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

Creator

Mohammad Dilshad Alam created and maintains this component.