How to Configure Wrapper Shapes (Circle, Square, Squircle) in Vue Color Avatar

The wrapper shape in Vue Color Avatar is controlled by the wrapperShape property in the avatar options, which maps to CSS styles via SHAPE_STYLE_SET and can be set programmatically or via the configurator UI.

Vue Color Avatar supports three distinct wrapper shapes—circle, square, and squircle—that frame the generated avatar SVG. You can configure these shapes programmatically through the WrapperShape enum or interactively via the configuration panel. This guide explains how the shape system works under the hood and how to customize it to match your design requirements.

Understanding the Wrapper Shape System

The wrapper shape system consists of type definitions, style mappings, and component rendering logic that work together to apply visual borders around the avatar.

Enum Definitions and Style Mappings

The available shapes are defined as a TypeScript enum in src/enums/index.ts at lines 33-37. The three built-in values are Circle, Square, and Squircle, each corresponding to a specific CSS border-radius configuration.

These enums map to concrete CSS rules via the SHAPE_STYLE_SET object in src/utils/constant.ts (lines 17-28). This constant exports a record that translates each WrapperShape value into a style object:

• Circle: Applies borderRadius: '50%' for a perfect circular mask
• Square: Applies borderRadius: '0' for sharp corners
• Squircle: Applies borderRadius: '25px' for a rounded-square appearance

Component Implementation

The root component src/components/VueColorAvatar.vue reads the selected shape from avatarOption.wrapperShape and applies the corresponding styles to the wrapper <div>. Lines 57-71 implement the getWrapperShapeStyle() function, which retrieves the correct style object from SHAPE_STYLE_SET and binds it to the container element's inline styles.

Configuring Shapes Via the UI

The configuration panel in src/components/Configurator.vue provides an interactive interface for selecting wrapper shapes. The component renders a visual list defined in SETTINGS.wrapperShape, displaying small preview squares that demonstrate each shape's border radius.

When a user clicks a shape option, the switchWrapperShape() method (lines 92-96) updates the global avatar state via the useAvatarOption hook. The active selection is highlighted using the .active CSS class, while each preview element uses class names (circle, square, squircle) that match the enum values to render the appropriate visual cue.

Setting Wrapper Shapes Programmatically

You can bypass the UI and set wrapper shapes directly through code when initializing or updating an avatar instance.

Using the Composition API Hook

Access the reactive avatar option through the useAvatarOption hook exported from src/hooks/useAvatarOption.ts. This hook returns a tuple containing the current options and a setter function:

import { WrapperShape } from '@/enums'
import { useAvatarOption } from '@/hooks'

const [avatarOption, setAvatarOption] = useAvatarOption()

// Switch to square wrapper
setAvatarOption({
  ...avatarOption.value,
  wrapperShape: WrapperShape.Square,
})

Passing Options to the Component

Alternatively, pass a complete options object directly to the VueColorAvatar component via the option prop:

<template>
  <VueColorAvatar :option="avatarConfig" size="320" />
</template>

<script setup lang="ts">
import VueColorAvatar from '@/components/VueColorAvatar.vue'
import { WrapperShape } from '@/enums'

const avatarConfig = {
  wrapperShape: WrapperShape.Circle,
  background: { color: '#8ec5fc', borderColor: 'transparent' },
  widgets: {
    // widget configuration...
  },
}
</script>

Creating Custom Wrapper Shapes

To implement a custom shape such as a hexagon, extend the existing enum and style system:

1. Extend the enum in src/enums/index.ts:

export enum WrapperShape {
  Circle = 'circle',
  Square = 'square',
  Squircle = 'squircle',
  Hexagon = 'hexagon',   // new entry
}

2. Add style mapping in src/utils/constant.ts:

export const SHAPE_STYLE_SET = {
  [WrapperShape.Circle]: { borderRadius: '50%' },
  [WrapperShape.Square]: { borderRadius: '0' },
  [WrapperShape.Squircle]: { borderRadius: '25px' },
  [WrapperShape.Hexagon]: {
    clipPath: 'polygon(25% 0%, 75% 0%, 100% 50%, 75% 100%, 25% 100%, 0% 50%)',
  },
}

3. Update the UI (optional): Add a new preview element in src/components/Configurator.vue with the corresponding CSS class.

Since SETTINGS.wrapperShape pulls from Object.values(WrapperShape), the new shape automatically appears in the configurator without additional registration.

Summary

• The wrapper shape is stored in avatarOption.wrapperShape and accepts WrapperShape.Circle, WrapperShape.Square, or WrapperShape.Squircle
• Style definitions live in src/utils/constant.ts within SHAPE_STYLE_SET, mapping enums to CSS properties like borderRadius
• The VueColorAvatar.vue component applies these styles to the root wrapper element at render time
• Use the useAvatarOption hook to programmatically update shapes in Composition API code
• Custom shapes require extending the enum in src/enums/index.ts and adding corresponding styles to SHAPE_STYLE_SET

Frequently Asked Questions

How do I toggle between circle and square shapes dynamically?

Use the useAvatarOption hook to read the current state and update it conditionally. Check avatarOption.value.wrapperShape against WrapperShape.Circle, then call setAvatarOption with WrapperShape.Square (or vice versa) to toggle between the two states.

Can I use percentage-based border radius for custom shapes?

Yes. When extending SHAPE_STYLE_SET in src/utils/constant.ts, you can specify borderRadius using any valid CSS unit, including percentages (e.g., borderRadius: '10%'). The style object supports all standard CSS properties, including clipPath for complex polygonal shapes.

Why doesn't my custom shape appear in the configurator panel?

Ensure you added the new enum value to src/enums/index.ts and that SETTINGS.wrapperShape in the configurator uses Object.values(WrapperShape) to generate its options list. If you hardcoded the shape list instead of using the enum values, you must manually add the new case to src/components/Configurator.vue.

What is the difference between square and squircle wrappers?

The square shape (WrapperShape.Square) applies zero border radius, creating sharp 90-degree corners. The squircle shape (WrapperShape.Squircle) applies a fixed 25-pixel border radius, creating rounded corners that soften the square appearance without forming a perfect circle.

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