How to Customize Border Color and Styles in vue-color-avatar

To customize border color and styles in vue-color-avatar, set the background.borderColor property in your AvatarOption object for dynamic colors, or modify the SCSS in src/components/widgets/Border.vue to change border width and style.

The vue-color-avatar library renders avatar borders through a dedicated Border.vue widget that consumes the avatarOption.background.borderColor value. Whether you need to match a brand color scheme or implement a specific design system, the component provides hooks at both the data layer (via props) and the presentation layer (via scoped styles).

Changing the Border Color

Via the AvatarOption Prop

The most maintainable way to customize border color is through the option prop passed to <VueColorAvatar>. The AvatarOption type defined in src/types/index.ts includes a background.borderColor field that accepts any valid CSS color string.

<script setup lang="ts">
import VueColorAvatar from '@/components/VueColorAvatar.vue'
import type { AvatarOption } from '@/types'

const customOption: AvatarOption = {
  background: {
    color: '#ffecd2',          // avatar fill color
    borderColor: '#ff7f50'     // custom border color
  },
  // ... other widget configurations
}
</script>

<template>
  <VueColorAvatar :option="customOption" />
</template>

In src/components/VueColorAvatar.vue, this value is forwarded to the Border widget:

<Border
  :color="avatarOption.background.borderColor"
  :radius="getWrapperShapeStyle().borderRadius"
/>

Programmatic Updates

If you generate avatars randomly but need to override the border color post-initialization, access the component instance and update the option object reactively:

import { ref, onMounted } from 'vue'
import VueColorAvatar from '@/components/VueColorAvatar.vue'
import type { AvatarOption } from '@/types'

const avatarRef = ref<InstanceType<typeof VueColorAvatar>>()
const currentOption = ref<AvatarOption>({})

onMounted(() => {
  // Update border color programmatically
  if (currentOption.value.background) {
    currentOption.value.background.borderColor = '#4caf50'
  }
})

Customizing Border Style and Width

Modifying Border.vue SCSS

The border width and style are hardcoded in the scoped styles of src/components/widgets/Border.vue. To customize these properties for your entire application, edit the .avatar-border class:

/* src/components/widgets/Border.vue */
.avatar-border {
  border-style: dashed;    /* solid, dotted, double, etc. */
  border-width: 4px;       /* any pixel value */
}

These styles apply to all avatar instances since Border.vue is a shared widget. The component uses CSS border properties rather than SVG strokes, ensuring crisp rendering at all sizes.

Adjusting Border Radius

Shape-Based Radius Configuration

The border radius derives from the avatar's wrapper shape (circle, square, or squircle). The mapping lives in src/utils/constant.ts within the SHAPE_STYLE_SET object:

// src/utils/constant.ts
export const SHAPE_STYLE_SET = {
  [WrapperShape.Circle]: { borderRadius: '50%' },
  [WrapperShape.Square]: { borderRadius: '0' },
  [WrapperShape.Squircle]: { borderRadius: '25px' },
}

When you set wrapperShape in your AvatarOption, the component automatically pulls the corresponding radius from this constant and passes it to Border.vue.

Custom Radius Values

To override the radius for a specific avatar without modifying global constants, pass a custom value directly to the Border component if you are building a custom wrapper:

<template>
  <Border
    :color="avatarOption.background.borderColor"
    radius="12px"
  />
</template>

Alternatively, extend SHAPE_STYLE_SET with a new shape enum value in src/enums/index.ts and add the corresponding radius configuration.

Complete Working Example

<template>
  <div class="demo">
    <VueColorAvatar :option="customOption" />
  </div>
</template>

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

const customOption: AvatarOption = {
  wrapperShape: WrapperShape.Squircle,
  background: {
    color: '#e3f2fd',
    borderColor: '#1976d2'  // Custom blue border
  }
  // widgets configuration omitted for brevity
}
</script>

<style scoped>
.demo {
  padding: 2rem;
}
</style>

With the SCSS modification in Border.vue (setting border-width: 6px and border-style: double), this renders a 6px double border in #1976d2 around the squircle avatar.

Summary

• Border color is controlled via avatarOption.background.borderColor passed to the color prop of Border.vue.
• Border width and style are defined in the scoped SCSS of src/components/widgets/Border.vue (.avatar-border class).
• Border radius derives from SHAPE_STYLE_SET in src/utils/constant.ts based on the selected WrapperShape.
• For dynamic applications, update the AvatarOption object reactively; for global changes, modify the widget’s source SCSS.

Frequently Asked Questions

How do I change only the border color without modifying other styles?

Provide an AvatarOption object with the background.borderColor property set to your desired CSS color value. This updates only the color while preserving the default 10px solid border width and style defined in Border.vue.

Can I use gradient colors for the avatar border?

Yes. The borderColor field accepts any valid CSS color string, including linear and radial gradients (e.g., linear-gradient(45deg, #ff6b6b, #4ecdc4)). Ensure your target browsers support CSS gradients on border properties.

Where is the default border width defined?

The default 10px width is hardcoded in the scoped styles of src/components/widgets/Border.vue within the .avatar-border class. Modify the border-width property in this file to change the default for all avatar instances.

How do I create a custom border radius for a new shape?

Add a new value to the WrapperShape enum in src/enums/index.ts, then add a corresponding entry to SHAPE_STYLE_SET in src/utils/constant.ts with your desired borderRadius value. The VueColorAvatar component will automatically apply this radius when the new shape is selected.

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