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

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 inside the exported SPECIAL_AVATARS array. Each entry is a complete AvatarOption object specifying the wrapper shape, background properties, and widget configurations.

// 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, the getSpecialAvatarOption function randomly selects one preset from the SPECIAL_AVATARS array using a simple index calculation.

// 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, 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.

// 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.

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 within the SPECIAL_AVATARS array.
• Random selection is handled by getSpecialAvatarOption() in src/utils/index.ts, which returns a random preset from the curated list.
• Trigger logic resides in 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 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 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 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, 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.

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