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

> Learn to configure wrapper shapes circle square and squircle in Vue Color Avatar using the wrapperShape property. Easily customize your avatar styles programmatically or via the UI.

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

---

**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`](https://github.com/codennnn/vue-color-avatar/blob/main/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`](https://github.com/codennnn/vue-color-avatar/blob/main/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`](https://github.com/codennnn/vue-color-avatar/blob/main/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`](https://github.com/codennnn/vue-color-avatar/blob/main/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`](https://github.com/codennnn/vue-color-avatar/blob/main/src/hooks/useAvatarOption.ts)**. This hook returns a tuple containing the current options and a setter function:

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

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

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

```

2. **Add style mapping** in **[`src/utils/constant.ts`](https://github.com/codennnn/vue-color-avatar/blob/main/src/utils/constant.ts)**:

```typescript
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`](https://github.com/codennnn/vue-color-avatar/blob/main/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`](https://github.com/codennnn/vue-color-avatar/blob/main/src/utils/constant.ts)** within `SHAPE_STYLE_SET`, mapping enums to CSS properties like `borderRadius`
- The **[`VueColorAvatar.vue`](https://github.com/codennnn/vue-color-avatar/blob/main/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`](https://github.com/codennnn/vue-color-avatar/blob/main/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`](https://github.com/codennnn/vue-color-avatar/blob/main/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`](https://github.com/codennnn/vue-color-avatar/blob/main/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`](https://github.com/codennnn/vue-color-avatar/blob/main/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.