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

> Customize avatar colors in vue-color-avatar by adjusting background and widget properties. Easily modify colors programmatically or via the Configurator UI for unique component designs.

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

---

**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`](https://github.com/codennnn/vue-color-avatar/blob/main/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`](https://github.com/codennnn/vue-color-avatar/blob/main/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`](https://github.com/codennnn/vue-color-avatar/blob/main/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`](https://github.com/codennnn/vue-color-avatar/blob/main/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`](https://github.com/codennnn/vue-color-avatar/blob/main/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`](https://github.com/codennnn/vue-color-avatar/blob/main/src/utils/constant.ts) as read-only getters on the `SETTINGS` object:

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

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

```typescript
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`](https://github.com/codennnn/vue-color-avatar/blob/main/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`](https://github.com/codennnn/vue-color-avatar/blob/main/VueColorAvatar.vue).
- **Extensible defaults**: Modify `commonColors`, `skinColors`, or the getter methods in [`constant.ts`](https://github.com/codennnn/vue-color-avatar/blob/main/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`](https://github.com/codennnn/vue-color-avatar/blob/main/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`](https://github.com/codennnn/vue-color-avatar/blob/main/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`](https://github.com/codennnn/vue-color-avatar/blob/main/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`](https://github.com/codennnn/vue-color-avatar/blob/main/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`](https://github.com/codennnn/vue-color-avatar/blob/main/src/utils/constant.ts) and rebuild the application.