# How the Special Avatar Preset System Works in vue-color-avatar

> Discover how vue-color-avatar's special avatar preset system randomly generates unique avatars from predefined configurations with adjustable probability. Learn more now.

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

---

**The special avatar preset system in vue-color-avatar randomly selects from a curated set of predefined avatar configurations stored in `SPECIAL_AVATARS` and applies them with a configurable probability when users generate new avatars.**

The vue-color-avatar library provides a surprise mechanism that occasionally serves handcrafted avatar designs instead of purely random combinations. This system ensures users encounter visually striking, curated configurations while maintaining the spontaneity of random generation. The implementation spans three key files that handle data definition, selection logic, and UI integration.

## Understanding the Special Avatar Preset Data

The special avatar preset system relies on a static array of complete avatar configurations. These presets define every visual aspect of an avatar, from background gradients to individual widget shapes and colors.

### Preset Definitions in constant.ts

All special presets live in [`src/utils/constant.ts`](https://github.com/codennnn/vue-color-avatar/blob/main/src/utils/constant.ts) inside the exported `SPECIAL_AVATARS` array. Each entry is a complete `AvatarOption` object specifying the wrapper shape, background properties, and widget configurations.

```typescript
// src/utils/constant.ts – lines 16-71
export const SPECIAL_AVATARS: Readonly<AvatarOption[]> = [
  {
    wrapperShape: 'squircle',
    background: {
      color: 'linear-gradient(62deg, #8EC5FC, #E0C3FC)',
      borderColor: 'transparent',
    },
    widgets: {
      face: { shape: FaceShape.Base, fillColor: '#F9C9B6' },
      tops: { shape: TopsShape.Pixie, fillColor: '#d2eff3' },
      // … other widgets …
    },
  },
  {
    wrapperShape: 'squircle',
    background: { color: '#fd6f5d', borderColor: 'transparent' },
    widgets: {
      // … another preset …
    },
  },
];

```

## How Presets Are Selected at Runtime

The library exposes a utility function that abstracts the random selection logic, making it reusable across components.

### The getSpecialAvatarOption Helper

Located in [`src/utils/index.ts`](https://github.com/codennnn/vue-color-avatar/blob/main/src/utils/index.ts), the `getSpecialAvatarOption` function randomly selects one preset from the `SPECIAL_AVATARS` array using a simple index calculation.

```typescript
// src/utils/index.ts – lines 48-50
export function getSpecialAvatarOption(): AvatarOption {
  return SPECIAL_AVATARS[Math.floor(Math.random() * SPECIAL_AVATARS.length)];
}

```

## Integration in the Application Flow

The main application logic determines when to trigger a special preset versus a standard random avatar, handling edge cases like duplicate prevention and UI consistency.

### The Generation Logic in App.vue

In [`src/App.vue`](https://github.com/codennnn/vue-color-avatar/blob/main/src/App.vue), the `handleGenerate` function implements the decision tree. It checks against `TRIGGER_PROBABILITY` (default 0.1), prevents consecutive identical presets, and preserves the user's selected wrapper shape.

```typescript
// src/App.vue – lines 31-41
function handleGenerate() {
  if (Math.random() <= TRIGGER_PROBABILITY) {
    let colorfulOption = getSpecialAvatarOption()
    // Ensure the new preset isn't identical to the current avatar
    while (JSON.stringify(colorfulOption) === JSON.stringify(avatarOption.value)) {
      colorfulOption = getSpecialAvatarOption()
    }
    // Keep the user's chosen wrapper shape
    colorfulOption.wrapperShape = avatarOption.value.wrapperShape
    setAvatarOption(colorfulOption)
    showConfetti()
  } else {
    const randomOption = getRandomAvatarOption(avatarOption.value)
    setAvatarOption(randomOption)
  }
}

```

The logic follows six distinct steps:

1. **Probability check** – `TRIGGER_PROBABILITY` determines if a special preset should appear.
2. **Random selection** – `getSpecialAvatarOption()` retrieves a curated preset.
3. **Duplication guard** – A `while` loop compares JSON strings to prevent identical consecutive avatars.
4. **Wrapper shape preservation** – The preset's `wrapperShape` is overwritten with the current user preference.
5. **State update** – `setAvatarOption` commits the new configuration to the store.
6. **Visual feedback** – `showConfetti()` triggers a celebration animation for special presets.

## Using Special Presets in Your Own Code

You can leverage the special avatar preset system in custom implementations by importing the utility directly.

```typescript
import { getSpecialAvatarOption } from '@/utils'

// Grab a random preset
const preset = getSpecialAvatarOption()

// Optionally adapt it (e.g., force a specific wrapper)
preset.wrapperShape = 'circle'

// Feed it to your VueColorAvatar instance
avatarRef.value?.setOption(preset)

```

This approach allows you to surface curated designs programmatically while maintaining full control over individual properties.

## Summary

- **Special avatar presets** are defined as static `AvatarOption` objects in [`src/utils/constant.ts`](https://github.com/codennnn/vue-color-avatar/blob/main/src/utils/constant.ts) within the `SPECIAL_AVATARS` array.
- **Random selection** is handled by `getSpecialAvatarOption()` in [`src/utils/index.ts`](https://github.com/codennnn/vue-color-avatar/blob/main/src/utils/index.ts), which returns a random preset from the curated list.
- **Trigger logic** resides in [`src/App.vue`](https://github.com/codennnn/vue-color-avatar/blob/main/src/App.vue), where `handleGenerate()` uses `TRIGGER_PROBABILITY` to decide between special presets and random generation.
- **User experience safeguards** include duplicate prevention and wrapper shape preservation to maintain UI consistency.
- **Direct usage** is possible by importing the utility function and calling it in your own components or scripts.

## Frequently Asked Questions

### Where are the special avatar presets defined in vue-color-avatar?

The presets are defined in [`src/utils/constant.ts`](https://github.com/codennnn/vue-color-avatar/blob/main/src/utils/constant.ts) as the `SPECIAL_AVATARS` array. Each entry is a complete `AvatarOption` object that specifies the wrapper shape, background colors, and all widget configurations including face, hair, and clothing.

### How does the app decide when to show a special preset instead of a random avatar?

The decision occurs in [`src/App.vue`](https://github.com/codennnn/vue-color-avatar/blob/main/src/App.vue) inside the `handleGenerate` function. The code generates a random number and compares it against `TRIGGER_PROBABILITY` (set to 0.1 by default). If the random number is less than or equal to this threshold, the app calls `getSpecialAvatarOption()` to retrieve a curated preset rather than generating a fully random avatar.

### Can I modify the special presets or add my own?

Yes. Since `SPECIAL_AVATARS` in [`src/utils/constant.ts`](https://github.com/codennnn/vue-color-avatar/blob/main/src/utils/constant.ts) is exported as a `Readonly` array, you would need to modify the source file directly to add or edit presets. Each preset must conform to the `AvatarOption` interface, defining all required properties including `wrapperShape`, `background`, and `widgets`.

### Why does the wrapper shape get overwritten when applying a special preset?

The wrapper shape is overwritten to respect the user's current UI preferences. In [`src/App.vue`](https://github.com/codennnn/vue-color-avatar/blob/main/src/App.vue), the code explicitly sets `colorfulOption.wrapperShape = avatarOption.value.wrapperShape` after selecting a special preset. This ensures that even when a curated avatar appears, it maintains the container shape (circle, squircle, etc.) that the user previously selected.