Angular Border Avatar

🎨 Live Demo

A lightweight Angular component for creating beautiful animated avatar borders with GIF support.

English | 中文

✨ Features

• 🎨 GIF Border Support - Support any GIF as avatar border
• 🎯 Highly Customizable - Full control over size, position, and rotation
• 📱 Responsive Design - Adapts to any screen size
• ⚡ Lightweight - Minimal dependencies, fast loading
• ♿ Accessible - Full ARIA support
• 🔄 Standalone - Angular Standalone component support

📦 Installation

npm install @luoxiao123/angular-border-avatar

🚀 Quick Start

import { Component } from '@angular/core';
import { BorderAvatarComponent, BorderAvatarConfig } from '@luoxiao123/angular-border-avatar';

@Component({
  selector: 'app-root',
  template: `
    <angular-border-avatar
      [avatarUrl]="avatarUrl"
      [borderConfig]="borderConfig"
      size="120px"
    ></angular-border-avatar>
  `,
  imports: [BorderAvatarComponent],
  standalone: true,
})
export class AppComponent {
  avatarUrl = 'https://api.dicebear.com/9.x/avataaars/svg?seed=user1';
  
  borderConfig: BorderAvatarConfig = {
    gifUrl: 'https://example.com/border.gif',
    avatarScale: 0.7,              // Avatar occupies 70% of container
    topOffsetRatio: 0.15,          // 15% of container height from top
    leftOffsetRatio: 0.15,         // 15% of container width from left
    borderRadius: '50%',            // Circle shape
    rotate: 0,                      // Rotation angle in degrees
  };
}

📋 Component API

Inputs

| Property | Type | Default | Description | |----------|------|---------|-------------| | avatarUrl | string \| null \| undefined | null | Avatar image URL. When null/undefined, uses default image | | borderConfig | BorderAvatarConfig \| null \| undefined | null | Border configuration. When null/undefined, border is hidden | | size | string | '120px' | Container size (px, rem, %, vw, etc.) | | altText | string | 'Avatar' | Image alt text | | clickable | boolean | false | Whether avatar is clickable | | lazyLoad | boolean | true | Enable lazy loading | | defaultImageUrl | string | SVG placeholder | Default image when loading fails |

BorderAvatarConfig

interface BorderAvatarConfig {
  gifUrl: string;           // Border GIF URL (required)
  avatarScale: number;      // Avatar scale ratio (0.3-0.9)
  topOffsetRatio: number;   // Vertical offset ratio (-0.2~0.2)
  leftOffsetRatio: number;  // Horizontal offset ratio (-0.2~0.2)
  borderRadius?: string;    // Border radius (default: '50%')
  rotate?: number;          // Rotation angle (default: 0)
}

Events

| Event | Type | Description | |-------|------|-------------| | imageLoad | EventEmitter<void> | Emitted when avatar image loads | | imageError | EventEmitter<string> | Emitted when image fails to load | | avatarClick | EventEmitter<MouseEvent> | Emitted when avatar is clicked |

Methods

| Method | Description | |--------|-------------| | recalculate() | Recalculate dimensions when container size changes |

💡 Usage Examples

Basic Usage

<angular-border-avatar
  [avatarUrl]="'https://example.com/avatar.jpg'"
  [borderConfig]="borderConfig"
  size="120px"
></angular-border-avatar>

Clickable Avatar

<angular-border-avatar
  [avatarUrl]="avatarUrl"
  [borderConfig]="borderConfig"
  [clickable]="true"
  (avatarClick)="onAvatarClick($event)"
  (imageError)="onImageError($event)"
></angular-border-avatar>

onAvatarClick(event: MouseEvent) {
  console.log('Avatar clicked!', event);
}

onImageError(error: string) {
  console.error('Failed to load image:', error);
}

Responsive Sizing

<div [style.width]="containerWidth + 'px'">
  <angular-border-avatar
    #avatar
    [avatarUrl]="avatarUrl"
    [borderConfig]="borderConfig"
    [size]="'100%'"
  ></angular-border-avatar>
</div>

import { ViewChild } from '@angular/core';
import { BorderAvatarComponent } from '@luoxiao123/angular-border-avatar';

export class MyComponent {
  @ViewChild(BorderAvatarComponent) avatar!: BorderAvatarComponent;

  changeDimensions() {
    // When container size changes, call recalculate method
    this.avatar.recalculate();
  }
}

Configuration Presets

Circle Avatar (Recommended)

const circleConfig: BorderAvatarConfig = {
  gifUrl: 'https://example.com/border.gif',
  avatarScale: 0.7,
  topOffsetRatio: 0.15,
  leftOffsetRatio: 0.15,
  borderRadius: '50%',
};

Square Avatar

const squareConfig: BorderAvatarConfig = {
  gifUrl: 'https://example.com/border.gif',
  avatarScale: 0.75,
  topOffsetRatio: 0.125,
  leftOffsetRatio: 0.125,
  borderRadius: '10px',
};

Rotating Border

const rotatingConfig: BorderAvatarConfig = {
  gifUrl: 'https://example.com/border.gif',
  avatarScale: 0.65,
  topOffsetRatio: 0.175,
  leftOffsetRatio: 0.175,
  borderRadius: '50%',
  rotate: 45,
};

🎨 Configuration Tips

Size Calculation Formula

Avatar Size = Container Size × avatarScale
Top Offset = Container Height × topOffsetRatio
Left Offset = Container Width × leftOffsetRatio

Best Practices

1. avatarScale: Set between 0.6-0.8 for optimal appearance
2. Offset Ratios: Keep within ±0.2 range to control avatar position
3. borderRadius: Match the avatar shape (50% for circle, other values for rectangle)
4. GIF Size: Keep GIF file size under 1MB for better performance

🌐 Browser Support

• Chrome (latest)
• Firefox (latest)
• Safari (latest)
• Edge (latest)

📄 License

MIT

🤝 Contributing

Contributions are welcome! Feel free to submit issues and pull requests.

📞 Support

If you have any questions, please open an issue on GitHub Issues.

English | 中文