How to Customize Skin Color Options for Avatar Components in VueColorAvatar

You can customize skin color options in VueColorAvatar either globally by modifying the SETTINGS.skinColors array in src/utils/constant.ts or per-instance by passing a custom AvatarOption object with a specific fillColor value to the widgets.face property.

The vue-color-avatar library provides a flexible system to customize skin color options for avatar components, allowing developers to tailor the default palette or override colors for individual instances. Whether you need to align avatars with your brand guidelines or offer users a specific set of skin tones, the component's architecture supports both global configuration and granular control. This guide explains the exact source files and methods you need to modify based on the actual implementation in the codennnn/vue-color-avatar repository.

Where Skin Colors Are Defined in VueColorAvatar

The default skin color palette is defined centrally in the SETTINGS constant located in src/utils/constant.ts. This read-only configuration object contains the skinColors array that specifies the hex color values available for avatar faces.

// src/utils/constant.ts
export const SETTINGS: Readonly<AvatarSettings> = {
  // ... other settings
  /** 🎨 Default skin colors */
  skinColors: ['#F8D9CE', '#F9C9B6', '#DEB3A3', '#C89583', '#9C6458'],
  // ...
}

When generating a random avatar, the getRandomAvatarOption function in src/utils/index.ts (line 87) calls getRandomFillColor and passes SETTINGS.skinColors as the source array. This randomly selects one of the defined hex values and assigns it to the face widget's fillColor property.

Global Customization: Modify the Default Skin Color Palette

To change the skin color options for all avatars throughout your application, edit the skinColors array in src/utils/constant.ts. This approach affects every call to getRandomAvatarOption() and ensures consistency across randomly generated avatars.

Add, remove, or reorder hex values to match your design requirements:

// src/utils/constant.ts
export const SETTINGS: Readonly<AvatarSettings> = {
  // ... other settings
  skinColors: [
    '#FFDBAC', // light
    '#F1C27D', // medium-light
    '#E0AC69', // medium
    '#C68642', // medium-dark
    '#8D5524', // dark
  ],
  // ...
}

After modifying this file, all subsequent avatar generations will draw from your custom palette. This method requires rebuilding or redeploying your application to take effect.

Per-Instance Customization: Override Skin Color for a Single Avatar

To set a specific skin color for an individual avatar without affecting the global palette, pass a custom AvatarOption object to the <VueColorAvatar> component. This approach provides granular control for specific use cases, such as displaying a user's selected profile color.

The option prop accepts an object where widgets.face.fillColor defines the skin tone:

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

const customOption: AvatarOption = {
  gender: 'female',
  wrapperShape: 'circle',
  background: {
    color: '#F4D150',
    borderColor: 'transparent',
  },
  widgets: {
    // Set specific skin color
    face: { shape: 'Base', fillColor: '#C68642' },
    
    // Other widgets can use defaults
    tops: { shape: 'Pixie', fillColor: '#48A99A' },
    ear: { shape: 'Attached' },
    earrings: { shape: 'none' },
    eyebrows: { shape: 'Up' },
    eyes: { shape: 'Round' },
    nose: { shape: 'Pointed' },
    glasses: { shape: 'none' },
    mouth: { shape: 'Smile' },
    beard: { shape: 'none' },
    clothes: { shape: 'Crew', fillColor: '#FFEDEF' },
  },
}
</script>

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

When you provide the option prop, the component bypasses the random generation logic and renders exactly what you specify. This allows you to store user preferences in a database and restore specific skin colors across sessions.

Combining Global and Per-Instance Approaches

You can extend the global palette while still allowing per-instance overrides. First, add your new colors to SETTINGS.skinColors in src/utils/constant.ts:

skinColors: [
  '#FFDBAC', '#F1C27D', '#E0AC69', '#C68642', '#8D5524',
  '#A57C56', // new custom shade
],

Then reference the new color in specific instances:

<VueColorAvatar :option="{ widgets: { face: { fillColor: '#A57C56' } } }" />

This hybrid approach maintains a curated palette for random generation while supporting explicit color selection when needed.

Key Files for Skin Color Customization

Understanding the codebase structure helps you implement changes confidently. These critical files control skin color behavior:

• src/utils/constant.ts – Defines the SETTINGS constant including the skinColors array (line 89). This is the central configuration for default skin tones.

• src/utils/index.ts – Contains getRandomAvatarOption (line 87) which calls getRandomFillColor(SETTINGS.skinColors) to randomly pick a color from the global palette during avatar generation.

• src/components/VueColorAvatar.vue – The main component that accepts an option prop (lines 42-48). When provided, this prop overrides the default random option, allowing specific skin color assignment via widgets.face.fillColor.

• src/types/index.ts – Defines the AvatarSettings and AvatarOption TypeScript interfaces (line 72), ensuring type safety when customizing skin colors programmatically.

These files together form the skin-color customization flow: the constant array supplies the default colors, the utility picks a random entry, and the component renders the final SVG. Adjust any of them according to the scope you need—global palette or per-avatar override.

Summary

• Global customization requires modifying the skinColors array in src/utils/constant.ts, affecting all randomly generated avatars in your application.
• Per-instance customization involves passing a custom AvatarOption object to the <VueColorAvatar> component with widgets.face.fillColor set to your desired hex value.
• The getRandomAvatarOption function in src/utils/index.ts automatically selects from the global palette when generating random avatars.
• TypeScript definitions in src/types/index.ts ensure that custom skin colors conform to the expected AvatarOption interface structure.

Frequently Asked Questions

How do I add a new skin color to the default palette?

Edit the skinColors array in src/utils/constant.ts and append or insert your new hex color code. For example, add '#A57C56' to the existing array. After saving, all future calls to getRandomAvatarOption() will include your new color in the random selection pool.

Can I set a specific skin color without modifying the global configuration?

Yes. Pass a custom option prop to the <VueColorAvatar> component containing widgets.face.fillColor set to your desired hex value. This overrides the random selection for that specific instance while leaving the global SETTINGS.skinColors array unchanged.

What file controls the random selection of skin colors?

The random selection logic resides in src/utils/index.ts within the getRandomAvatarOption function (line 87). This function calls getRandomFillColor(SETTINGS.skinColors) to randomly pick a color from the global palette defined in src/utils/constant.ts.

Is there a TypeScript type definition for skin color options?

Yes. The AvatarSettings interface in src/types/index.ts (line 72) defines the structure for skinColors as a string array. When customizing per-instance colors, use the AvatarOption interface which specifies that widgets.face.fillColor accepts a string hex value.

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