ng-hub-ui-avatar
Version:
A powerful, flexible, and standalone Angular avatar component that generates and fetches user avatars from multiple sources including social media, Gravatar, or custom images with intelligent fallback system
170 lines (132 loc) • 8.68 kB
Markdown
# ng-hub-ui-avatar
[](https://badge.fury.io/js/ng-hub-ui-avatar)
[](https://www.npmjs.com/package/ng-hub-ui-avatar)
## Part of ng-hub-ui Family
This component is part of the ng-hub-ui ecosystem, which includes:
- [ng-hub-ui-table](https://www.npmjs.com/package/ng-hub-ui-table)
- [ng-hub-ui-modal](https://www.npmjs.com/package/ng-hub-ui-modal)
- [ng-hub-ui-stepper](https://www.npmjs.com/package/ng-hub-ui-stepper)
- [ng-hub-ui-breadcrumbs](https://www.npmjs.com/package/ng-hub-ui-breadcrumbs)
- [ng-hub-ui-portal](https://www.npmjs.com/package/ng-hub-ui-portal)
## Credits and Attribution
This library is a fork of [ngx-avatars](https://github.com/Heatmanofurioso/ngx-avatars), originally created by [HaithemMosbahi](https://github.com/HaithemMosbahi) and maintained by [Tiago Casinhas](https://github.com/Heatmanofurioso).
The original work provided an excellent foundation for avatar management in Angular applications. This fork was created to:
- Provide a standalone component architecture
- Ensure compatibility with the latest Angular versions
- Integrate seamlessly with the ng-hub-ui component ecosystem
- Add new features and improvements while maintaining the original functionality
All credit for the original implementation goes to the original authors and contributors of ngx-avatars.
## Description
A versatile avatar component for Angular applications that fetches or generates avatars based on user information. The component includes a sophisticated fallback system that attempts different sources if the primary source fails.
You can use this component with either a single source or multiple avatar sources, with the fallback system automatically selecting the first valid avatar.
Additionally, the component can display name initials or custom values as avatars.
Supported avatar sources:
* Facebook
* Google
* Twitter
* Instagram
* Vkontakte (VK)
* Skype
* Gravatar (🚧 Under construction)
* GitHub
* Custom image
* Name initials
* Value
The fallback system follows the same order as the source list above, with Facebook having the highest priority.
## Installation
Install the avatar component using npm:
```bash
npm install ng-hub-ui-avatar --save
```
Or using yarn:
```bash
yarn add ng-hub-ui-avatar
```
## Usage
As this is a standalone component, you don't need to import any module. Just import the component directly in your standalone components or pages:
```typescript
import { Component } from '@angular/core';
import { NgHubUiAvatar } from 'ng-hub-ui-avatar';
@Component({
selector: 'app-my-component',
standalone: true,
imports: [NgHubUiAvatar],
template: `
<ng-hub-ui-avatar></ng-hub-ui-avatar>
`
})
export class MyComponent { }
```
If you're using NgModule (legacy approach), you can import it in your components array:
```typescript
import { NgModule } from '@angular/core';
import { NgHubUiAvatar } from 'ng-hub-ui-avatar';
@NgModule({
imports: [
// other imports...
],
declarations: [AppComponent],
bootstrap: [AppComponent]
})
export class AppModule { }
```
Use it in your components:
```html
<ng-hub-ui-avatar></ng-hub-ui-avatar>
```
## Examples
```html
<ng-hub-ui-avatar facebookId="1508319875"></ng-hub-ui-avatar>
<ng-hub-ui-avatar googleId="1508319875"></ng-hub-ui-avatar>
<ng-hub-ui-avatar twitterId="1508319875"></ng-hub-ui-avatar>
<ng-hub-ui-avatar instagramId="dccomics" size="70"></ng-hub-ui-avatar>
<ng-hub-ui-avatar name="John Doe"></ng-hub-ui-avatar>
<ng-hub-ui-avatar value="75%"></ng-hub-ui-avatar>
<!-- Multiple sources with fallback -->
<ng-hub-ui-avatar
facebookId="userFacebookID"
skypeId="userSkypeID"
googleId="google"
name="John Doe"
src="assets/avatar.jpg"
value="28%"
size="100"
[round]="true">
</ng-hub-ui-avatar>
```
## Options
| Attribute | Type | Default | Description |
|------------------|------------|-----------|--------------------------------------------------------------------------------------------------------------------------------------|
| `facebookId` | *string* | null | Facebook ID |
| `googleId` | *string* | null | Google ID |
| `twitterId` | *string* | null | Twitter Handle |
| `instagramId` | *string* | null | Instagram Handle |
| `vkontakteId` | *string* | null | VK ID |
| `skypeId` | *string* | null | Skype ID |
| `githubId` | *string* | null | Github ID |
| `src` | *string* | null | Fallback image to use |
| `name` | *string* | null | Will be used to generate avatar based on initials |
| `value` | *string* | null | Show a value as avatar |
| `initialsSize` | *number* | 0 | Limits the number of characters in initials (0 = no limit) |
| `bgColor` | *string* | random | Background color (hex format, e.g., #FF0000) |
| `fgColor` | *string* | #FFF | Text color (hex format, e.g., #FF0000) |
| `size` | *number* | 50 | Size of the avatar |
| `textSizeRatio` | *number* | 3 | Text size as a fraction of avatar size |
| `round` | *boolean* | true | Round the avatar corners |
| `cornerRadius` | *number* | 0 | Border radius for square avatars |
| `borderColor` | *string* | undefined | Border color |
| `style` | *object* | | Custom styles for root element |
| `clickOnAvatar` | *Output* | | Event emitted on avatar click |
| `referrerpolicy` | *string* | null | Referrer policy for image requests |
## Support the Project
If you find this library helpful, consider supporting its development:
[](https://www.buymeacoffee.com/carlosmorcillo)
## Contributing
Contributions are welcome! Here's how you can help:
1. Fork the repository
2. Create your feature branch: `git checkout -b feature/my-new-feature`
3. Commit your changes: `git commit -am 'Add some feature'`
4. Push to the branch: `git push origin feature/my-new-feature`
5. Submit a pull request
## License
MIT © [Carlos Morcillo](mailto:contact@carlosmorcillo.dev)