# How Vue Color Avatar's z-index Layering System Manages Component Order
> Discover how Vue Color Avatar's z-index layering system expertly manages avatar component order using data-driven sorting and CSS stacking for precise visual control.
- Repository: [LeoKu/vue-color-avatar](https://github.com/codennnn/vue-color-avatar)
- Tags: internals
- Published: 2026-02-27
---
**Vue Color Avatar uses a two-step z-index layering system that combines data-driven widget sorting with CSS stacking to control the visual order of avatar components.**
The **z-index layering system** in the [vue-color-avatar](https://github.com/codennnn/vue-color-avatar) repository determines how facial features, accessories, and borders stack to create a cohesive avatar image. This system operates at both the data level—sorting SVG widgets before rendering—and the DOM level—using CSS `z-index` to separate background, content, and border layers.
## Understanding the Two-Step z-index Layering System
The avatar component implements a hybrid approach that separates logical ordering from visual stacking. This ensures that widgets render in the correct sequence while maintaining clean separation between the background, SVG payload, and border elements.
### Data-Driven z-index Values
Each widget in an `AvatarOption` configuration can specify an explicit `zIndex` property. When omitted, the system falls back to default values defined in [`src/utils/constant.ts`](https://github.com/codennnn/vue-color-avatar/blob/main/src/utils/constant.ts) within the `AVATAR_LAYER` constant.
The default stack assigns specific z-index values to widget types to ensure logical facial composition:
- **Face**: 10
- **Eyes**: 20
- **Eyebrows**: 30
- **Glasses**: 90
- **Hair**: 80
- **Ears**: 102
- **Clothes**: 110
This configuration ensures that clothes appear above the body, ears sit properly on the head, and glasses overlay eyes correctly.
### Runtime Sorting and SVG Composition
In [`src/components/VueColorAvatar.vue`](https://github.com/codennnn/vue-color-avatar/blob/main/src/components/VueColorAvatar.vue), the component transforms the widget object into a sorted array before generating the final SVG. The sorting logic (lines 75-80) compares the effective z-index of each widget—either the explicit value or the default from `AVATAR_LAYER`.
```typescript
// VueColorAvatar.vue – sorting logic
const sortedList = Object.entries(avatarOption.value.widgets).sort(
([, prev], [, next]) => {
const ix = prev.zIndex ?? AVATAR_LAYER[prev.shape]?.zIndex ?? 0
const iix = next.zIndex ?? AVATAR_LAYER[next.shape]?.zIndex ?? 0
return ix - iix
}
)
```
Because SVG renders elements in document order, later groups automatically appear above earlier ones. The sorted array ensures that high z-index widgets are appended last, placing them visually on top.
## CSS z-index Layering in the DOM
While the data layer manages widget ordering within the SVG, CSS handles the macro-level stacking of the avatar's major components.
The root wrapper (`.vue-color-avatar`) uses `position: relative` to establish a stacking context. Three primary layers exist:
1. **Background** ([`Background.vue`](https://github.com/codennnn/vue-color-avatar/blob/main/Background.vue)): Absolutely positioned with no explicit z-index, placing it at the bottom of the stack (lines 16-21).
2. **SVG Payload** (`.avatar-payload`): Assigned `z-index: 2` (lines 44-50 in [`VueColorAvatar.vue`](https://github.com/codennnn/vue-color-avatar/blob/main/VueColorAvatar.vue)), ensuring it renders above the background but below the border.
3. **Border** ([`Border.vue`](https://github.com/codennnn/vue-color-avatar/blob/main/Border.vue)): Absolutely positioned with `z-index: 3` (lines 20-25), creating the topmost overlay that frames the entire avatar.
This separation allows the border to consistently frame the avatar regardless of the internal widget configuration, while the background remains firmly behind all facial features.
## Practical Examples
### Overriding Default Layer Order
To force glasses to appear above hair (useful for certain hairstyles), explicitly set a higher `zIndex`:
```typescript
import { AvatarOption } from '@/types'
const customOption: AvatarOption = {
widgets: {
face: { shape: 'base', fillColor: '#F9C9B6' },
hair: { shape: 'pixie', fillColor: '#d2eff3', zIndex: 80 },
glasses: { shape: 'round', zIndex: 200 }, // Forces glasses to front
clothes: { shape: 'hoodie', fillColor: '#6c8cff' }
}
}
```
### Using the Default Stack
For standard avatar generation, omit the `zIndex` property and rely on the library's internal defaults:
```typescript
import { getRandomAvatarOption } from '@/utils'
// Generates random avatar using AVATAR_LAYER defaults
```
### Inspecting the Rendered Order
To verify the layering system in the browser:
1. Open DevTools and locate the generated `