# How to Customize Skin Color Options for Avatar Components in VueColorAvatar

> Customize skin color options for VueColorAvatar components globally or per instance. Learn how to modify settings or pass custom options to personalize your avatars.

- Repository: [LeoKu/vue-color-avatar](https://github.com/codennnn/vue-color-avatar)
- Tags: how-to-guide
- Published: 2026-02-27

---

**You can customize skin color options in VueColorAvatar either globally by modifying the `SETTINGS.skinColors` array in [`src/utils/constant.ts`](https://github.com/codennnn/vue-color-avatar/blob/main/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`](https://github.com/codennnn/vue-color-avatar/blob/main/src/utils/constant.ts). This read-only configuration object contains the `skinColors` array that specifies the hex color values available for avatar faces.

```typescript
// 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`](https://github.com/codennnn/vue-color-avatar/blob/main/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`](https://github.com/codennnn/vue-color-avatar/blob/main/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:

```typescript
// 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:

```vue
<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`](https://github.com/codennnn/vue-color-avatar/blob/main/src/utils/constant.ts):

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

```

Then reference the new color in specific instances:

```vue
<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`](https://github.com/codennnn/vue-color-avatar/blob/main/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`](https://github.com/codennnn/vue-color-avatar/blob/main/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`](https://github.com/codennnn/vue-color-avatar/blob/main/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`](https://github.com/codennnn/vue-color-avatar/blob/main/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`](https://github.com/codennnn/vue-color-avatar/blob/main/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`](https://github.com/codennnn/vue-color-avatar/blob/main/src/utils/index.ts) automatically selects from the global palette when generating random avatars.
- TypeScript definitions in [`src/types/index.ts`](https://github.com/codennnn/vue-color-avatar/blob/main/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`](https://github.com/codennnn/vue-color-avatar/blob/main/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`](https://github.com/codennnn/vue-color-avatar/blob/main/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`](https://github.com/codennnn/vue-color-avatar/blob/main/src/utils/constant.ts).

### Is there a TypeScript type definition for skin color options?

Yes. The `AvatarSettings` interface in [`src/types/index.ts`](https://github.com/codennnn/vue-color-avatar/blob/main/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.