How to Customize Colors for Avatar Components in vue-color-avatar

You can customize avatar colors in vue-color-avatar by modifying the AvatarOption object's background and widgets properties, either through the built-in Configurator UI or programmatically via component props.

The vue-color-avatar library generates avatars by layering SVG widget elements inside a wrapper component. To customize colors for avatar components effectively, you need to understand how colors are applied at three distinct architectural levels: background fills, border strokes, and widget skin tones.

Understanding the Color Architecture

Colors in vue-color-avatar are controlled through the AvatarOption type defined in src/types/index.ts. The system separates color concerns into three hierarchical levels to give you granular control over the final render.

Background Colors

The background layer controls the solid color or gradient that fills the entire avatar canvas. In src/components/widgets/Background.vue, the component binds the background style directly to props.color. The default palette lives in SETTINGS.backgroundColor inside src/utils/constant.ts, which includes solid hex codes, CSS gradients like linear-gradient(45deg, #E3648C, #D97567), and a transparent option.

Border Colors

The border layer defines the outer stroke around the avatar shape. The src/components/widgets/Border.vue component renders this using the borderColor style bound to props.color. Valid values are sourced from SETTINGS.borderColor in the constants file, which combines commonColors with a transparent option to remove the border entirely.

Widget Fill Colors

Widget colors control the skin tones and clothing fills for individual avatar elements like faces, ears, tops, and clothes. These are applied through the fillColor property within each widget configuration. The SVG markup for each widget contains $fillColor placeholders that src/components/VueColorAvatar.vue replaces at runtime via a watchEffect hook. Skin-specific widgets (Face, Ear) pull from SETTINGS.skinColors, while other widgets use SETTINGS.commonColors.

Where Color Palettes Are Defined

All default color palettes are centralized in src/utils/constant.ts as read-only getters on the SETTINGS object:

export const SETTINGS: Readonly<AvatarSettings> = {
  commonColors: ['#6BD9E9', '#FC909F', '#F4D150', '#E0DDFF', '#D2EFF3', '#FFEDEF'],
  skinColors: ['#F8D9CE', '#F9C9B6', '#E6A07C', '#E5A07C', '#FFDCB1', '#F0D5BA'],
  get backgroundColor() {
    return [...this.commonColors, 'linear-gradient(45deg, #E3648C, #D97567)', 'linear-gradient(62deg, #8EC5FC, #E0C3FC)', 'linear-gradient(90deg, #FF9A9E, #FECFEF)', 'transparent']
  },
  get borderColor() {
    return [...this.commonColors, 'transparent']
  },
}

The src/components/Configurator.vue UI consumes these arrays to render color picker lists. When you select a color, the UI calls specific mutators that dispatch Pinia store mutations defined in src/store/index.ts:

• switchBgColor(bgColor: string) updates avatarOption.background.color
• switchBorderColor(borderColor: string) updates avatarOption.background.borderColor
• setWidgetColor(widgetType, fillColor) updates avatarOption.widgets[widgetType].fillColor

The store's SET_AVATAR_OPTION mutation pushes a new AvatarOption into the history stack, triggering a reactive re-render of the avatar components.

Methods to Customize Avatar Colors

Using the Built-in Configurator UI

The simplest way to customize colors for avatar components is through the <Configurator> component included in the library. This side-panel interface automatically lists all available colors from the SETTINGS object:

1. Background Color: Select from solid colors, gradients, or transparent in the Background Color section.
2. Border Color: Choose a stroke color or set it to transparent to remove the border entirely.
3. Widget Colors: Click any widget category (Face, Tops, Clothes, etc.) to reveal color swatches specific to that element. Skin tones use the skinColors palette, while clothing and accessories use commonColors.

Programmatic Color Customization

For dynamic applications or headless rendering, pass an AvatarOption object directly to the VueColorAvatar component. Only the fields you specify will override defaults; omitted fields inherit from the library's internal defaults.

<script setup lang="ts">
import { ref } from 'vue'
import VueColorAvatar from '@/components/VueColorAvatar.vue'
import type { AvatarOption } from '@/types'

const customOption = ref<AvatarOption>({
  wrapperShape: 'circle',
  background: {
    // Supports hex, rgb(), rgba(), hsl(), gradients, or transparent
    color: 'linear-gradient(62deg, #8EC5FC, #E0C3FC)',
    borderColor: '#ff4757',
  },
  widgets: {
    // Face skin tone
    face: { shape: 'Base', fillColor: '#F9C9B6' },
    
    // Hair/top color
    tops: { shape: 'Pixie', fillColor: '#48A99A' },
    
    // Clothing color
    clothes: { shape: 'Crew', fillColor: '#FFEDEF' },
  },
})
</script>

<template>
  <VueColorAvatar :option="customOption" :size="300" />
</template>

The background.color property accepts any valid CSS color string, including complex gradients. The widgets object maps WidgetType keys to configuration objects containing fillColor, which the rendering engine substitutes for $fillColor placeholders in the SVG templates.

Extending the Default Color Palette

To add new preset colors to the Configurator UI, modify the SETTINGS object in src/utils/constant.ts:

export const SETTINGS: Readonly<AvatarSettings> = {
  commonColors: [
    '#6BD9E9',
    '#FC909F',
    '#F4D150',
    '#E0DDFF',
    '#D2EFF3',
    '#FFEDEF',
    '#9B59B6',  // New purple hue
    '#2ECC71',  // New green hue
  ],
  skinColors: [
    '#F8D9CE',
    '#F9C9B6',
    '#E6A07C',
    '#E5A07C',
    '#FFDCB1',
    '#F0D5BA',
    '#8D5524',  // New darker skin tone
  ],
  // ... getters remain unchanged
}

After modifying the constants, restart the Vite development server. The Configurator component automatically picks up the new arrays and renders additional color swatches in the appropriate sections without requiring changes to the UI components.

Summary

• Three color levels: Background fills, border strokes, and widget skin/fill colors are controlled independently through the AvatarOption interface.
• Centralized palettes: Default colors live in src/utils/constant.ts within the SETTINGS object, consumed by both the Configurator UI and the rendering engine.
• Two customization paths: Use the built-in <Configurator> component for interactive selection, or pass a configured AvatarOption object to <VueColorAvatar> for programmatic control.
• Dynamic rendering: Color changes trigger reactive updates through Pinia store mutations (SET_AVATAR_OPTION), with SVG placeholders replaced at runtime in VueColorAvatar.vue.
• Extensible defaults: Modify commonColors, skinColors, or the getter methods in constant.ts to add new preset swatches to the UI.

Frequently Asked Questions

Can I use CSS gradients for avatar backgrounds?

Yes. The background.color field in AvatarOption accepts any valid CSS color string, including linear and radial gradients. For example, you can set color: 'linear-gradient(62deg, #8EC5FC, #E0C3FC)' to create a gradient background. The Background.vue widget binds this directly to the CSS background property.

How do I remove the border around the avatar?

Set the background.borderColor property to "transparent". The Border.vue component checks this value and will render an invisible border when transparent is selected. This option is available in the default SETTINGS.borderColor array defined in src/utils/constant.ts.

What is the difference between commonColors and skinColors?

commonColors defines the palette for clothing, accessories, hair, and background elements, while skinColors specifically provides tones for face and ear widgets. The Configurator.vue component renders these in separate sections, and the rendering engine uses skinColors for WidgetType.Face and WidgetType.Ear to ensure realistic skin tone selection.

Can I add custom colors without modifying the source code?

For programmatic usage, yes. When passing an AvatarOption to the VueColorAvatar component, you can specify any hex code, RGB value, or CSS gradient string in the fillColor and color fields without touching the library source. However, to add new preset swatches to the built-in Configurator UI, you must extend the SETTINGS object in src/utils/constant.ts and rebuild the application.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}