ngx-avatar-letters/README.md

Angular component to generate avatar initials with configurable styles.

# ngx-avatar-letters

> Angular component to generate avatar initials with configurable styles.

[![npm version](https://img.shields.io/npm/v/ngx-avatar-letters.svg)](https://www.npmjs.com/package/ngx-avatar-letters)
[![Downloads](https://img.shields.io/npm/dw/ngx-avatar-letters.svg)](https://www.npmjs.com/package/ngx-avatar-letters)
 
---

## ✨ Major Features

✅ Generates initials automatically  
✅ Customizable size, colors, shape  
✅ Fallback to initials if no image provided  
✅ Lightweight and zero dependencies  
✅ Works with **Standalone Components** and **NgModules**

---

## 🚀 Installation

Install the package via npm:

```bash
npm install --save ngx-avatar-letters
```

or with yarn:

```bash
yarn add ngx-avatar-letters
```

##  ⚙️ Basic Usage
### Import the Component

If you’re using Angular standalone components:

```typescript
import { AvatarLettersComponent } from 'ngx-avatar-letters';

@Component({
  standalone: true,
  imports: [AvatarLettersComponent],
  template: `
    <ngx-avatar-letters [config]="avatarConfig"></ngx-avatar-letters>
  `,
})
export class DemoComponent {
  avatarConfig = {
    name: 'José Leonardo Matiz',
    size: 60,
    shape: 'circle',
    bgColor: '#3f51b5',
    textColor: '#fff',
    imageUrl: ''
  };
}
```

Or import the module in your NgModule:

```typescript
import { NgxAvatarLettersModule } from 'ngx-avatar-letters';

@NgModule({
  imports: [NgxAvatarLettersModule],
})
export class AppModule {}
```

  
### Template
```html
<ngx-avatar-letters [config]="avatarConfig"></ngx-avatar-letters>
```

And in your component:

```typescript
avatarConfig = {
  name: 'José Leonardo Matiz',
  size: 60,
  shape: 'circle',
  bgColor: '#3f51b5',
  textColor: '#fff',
  imageUrl: ''
};
```
## 📦 Component API
The component accepts a single input called config of type AvatarConfig:

```typescript
export interface AvatarConfig {
  /** Full name to generate initials */
  name: string;
  /** Size in pixels (default: 40) */
  size?: number;
  /** Background color (default: random) */
  bgColor?: string;
  /** Text color (default: #fff) */
  textColor?: string;
  /** Shape: 'circle' or 'square' (default: 'circle') */
  shape?: 'circle' | 'square';
  /** Optional image URL */
  imageUrl?: string;
}
```
 
## 🎯 Compatibility
Angular 17+

Modern browsers



## 📦 License
MIT © 2025



---

## ☕ Buy Me a Coffee

If you find this library helpful, you can support my work:

[![Buy Me A Coffee](https://media1.giphy.com/media/v1.Y2lkPTc5MGI3NjExN3l0ejVuamdpbnVlaTNqN21jMXg0aXE5YTV5dHJ5N2lnZGNrampodCZlcD12MV9pbnRlcm5hbF9naWZfYnlfaWQmY3Q9cw/o7RZbs4KAA6tvM4H6j/giphy.gif)](https://buymeacoffee.com/leonardomatiz)

👉 [Buy Me a Coffee](https://buymeacoffee.com/leonardomatiz)


## 🔑 Keywords
  
angular, ngx, avatar, avatars, avatar initials, initials, avatar letters, letter avatar, ngx-avatar, angular avatar, angular avatar letters, user avatar, profile avatar, dynamic avatar, avatar generator, angular component, angular standalone, ngx library, angular library, ui component, ngmodule, standalone component, image fallback, random color avatar, avatar image, ng avatar