Vue Boring Avatars

1.4.0 · active · verified Sun Apr 19

vue-boring-avatars is a dedicated Vue 3 library that generates customizable, SVG-based user avatars. It is a direct port of the popular `Boring Avatars` JavaScript library, ensuring API parity with its React counterpart. Currently at stable version `1.4.0`, the library demonstrates an active release cadence, frequently updating to match new features and improvements introduced in the upstream `Boring Avatars` project. Key differentiators include its full support for Vue 3 and TypeScript, the provision of type definitions out-of-the-box, and robust accessibility features, such as `role` and `title` attributes for generated SVGs. It offers various avatar patterns (bauhaus, beam, marble, pixel, ring, sunset) and allows extensive customization through name, size, square shape, and color palettes, making it a flexible choice for profile picture generation.

Common errors

```
[Vue warn]: Failed to resolve component: Avatar
```
cause The `Avatar` component was imported but not correctly registered within the Vue application or the parent component's `components` option.

fix Ensure `Avatar` is explicitly added to the `components` object in your Vue component options (e.g., `components: { Avatar }`) or, if using `<script setup>`, verify the import path is correct.
```
TypeError: Cannot read properties of undefined (reading 'setup') (or similar module resolution error when using require())
```
cause Attempting to use `require()` syntax with the library's primary ESM export in a CommonJS environment, which is not directly compatible without specific bundler configurations or explicit targeting of the UMD build.

fix For modern Vue 3 development, use `import Avatar from 'vue-boring-avatars';`. If you are in a legacy CommonJS environment, ensure your bundler properly handles ESM-CJS interop, or directly import the UMD bundle from `node_modules/vue-boring-avatars/dist/vue-boring-avatars.umd.cjs`.

Warnings

breaking This library is strictly designed for Vue 3. Attempting to use `vue-boring-avatars` within a Vue 2 project will lead to runtime errors due to incompatible component APIs and lifecycle hooks.
Fix: Ensure your project is running Vue 3. If you require a Vue 2 compatible version, consider using alternative implementations like `vue2-boring-avatars`.
gotcha The `name` prop defaults to 'Clara Barton' and `colors` to a specific palette if not explicitly provided. For truly dynamic or empty avatars, always pass a unique `name` string and your desired `colors` array.
Fix: Always provide the `name` prop with a unique string (e.g., from user data) and the `colors` prop with your custom color array for consistent and dynamic avatar generation.
gotcha When using CDN, ensure you choose the correct bundle. `vue-boring-avatars.js` is for ESM environments, while `vue-boring-avatars.umd.cjs` is for UMD/CommonJS environments. Mixing them or using the wrong one for your setup can lead to module resolution issues.
Fix: For modern browser environments supporting ES modules, use `<script type="module" src=".../vue-boring-avatars.js">`. For older environments or when bundling with CJS, use the UMD version or rely on npm/yarn/pnpm installations with appropriate bundler configurations.

Install

npm install vue-boring-avatars npm
yarn add vue-boring-avatars yarn
pnpm add vue-boring-avatars pnpm

Imports

Avatar
```
import Avatar from 'vue-boring-avatars';
```
This is the primary component and the recommended ESM import for Vue 3 projects.
Avatar
wrong:
```
const Avatar = require('vue-boring-avatars');
```
correct:
This CommonJS `require` syntax is generally incompatible with Vue 3's ESM-first approach unless specifically targeting the UMD build or using a bundler that handles CJS-ESM interop.
Avatar (in <script setup>)
```

<script setup>
import Avatar from 'vue-boring-avatars';
</script>
```
When using Vue 3's `<script setup>`, the imported component is automatically made available in the template without explicit registration.

Quickstart

This example demonstrates how to integrate and use the `Avatar` component with various props in a Vue 3 Composition API setup, including dynamic name and size, different variants, and accessibility features.

<template>
  <input type="text" v-model="name" placeholder="Enter name" />
  <input type="number" v-model.number="size" min="20" max="200" placeholder="Enter size" />

  <h3>Bauhaus Variant</h3>
  <Avatar :size="size" variant="bauhaus" :name="name" :colors="['#92A1C6', '#146A7C', '#F0AB3D', '#C271B4', '#C20D90']" />

  <h3>Beam Variant (Square, with title)</h3>
  <Avatar :size="size" variant="beam" :name="name" :square="true" :title="true" :id="'beam-avatar'" />

  <h3>Marble Variant (Default)</h3>
  <Avatar :size="size" variant="marble" :name="name" />

  <h3>Pixel Variant</h3>
  <Avatar :size="size" variant="pixel" :name="name" :square="true" :title="true" />
</template>

<script lang="ts">
import { defineComponent, ref } from 'vue';
import Avatar from 'vue-boring-avatars';

export default defineComponent({
  name: 'AvatarDemo',
  setup() {
    const name = ref('Clara Barton');
    const size = ref(80);

    return {
      name,
      size
    };
  },
  components: {
    Avatar
  }
});
</script>

view raw JSON →