npm package: @jotnar/m-avatar
Description: A reusable Vue 3 avatar component with Tailwind CSS support
Author: Jotnar
Latest version: 0.1.1

# @jotnar/m-avatar

A versatile Vue 3 avatar component with Tailwind CSS 4 styling, designed for displaying user avatars, initials, and status indicators with customizable sizes, colors, and variants.

## 📦 Installation

Install the package via npm:

```bash
npm i @jotnar/m-avatar@latest
```

**Prerequisites:** Ensure your project has Vue 3 (version 3.4.0 or higher) and Tailwind CSS 4 set up, as this component relies on Tailwind CSS classes for styling and Vue 3 for functionality.

## 🧑‍💻 Usage

You can use the **m-avatar** component in your Vue 3 application either by registering it globally or locally in specific components.

### 🌐 Global Registration

Register the **m-avatar** component globally in your Vue app:

1. Import the component in your main JavaScript file (e.g., main.js):

```javascript
import { createApp } from 'vue'
import App from './App.vue'
import { MAvatar } from '@jotnar/m-avatar'

const app = createApp(App)
app.component('m-avatar', MAvatar)
app.mount('#app')
```

2. Import the styles in your main CSS file (e.g., main.css):

```css
@import '@jotnar/m-avatar/style';
@import 'tailwindcss';
```

Once these steps are complete, you can use the <m-avatar> component anywhere in your app.

### 📦 Local Registration

Import and use the component in specific components:

```html
<template>
  <m-avatar src="user.jpg" name="John Doe" color="primary" status="online" />
</template>

<script setup>
  import { MAvatar } from '@jotnar/m-avatar'
</script>
```

## 🎛️ Props

The **m-chip** component offers a range of props to customize its appearance and behavior:

| Prop       | Type    | Default     | Description                                                                    |
| ---------- | ------- | ----------- | ------------------------------------------------------------------------------ |
| `src`      | String  | `null`      | URL of the avatar image.                                                       |
| `name`     | String  | `null`      | Name used for initials (displays first letter if no src).                      |
| `status`   | String  | `null`      | Status indicator: online, offline, away, busy, no disturb, or null.            |
| `avatars`  | Array   | `null`      | Array of avatar image URLs for group avatars.                                  |
| `limit`    | Number  | `4`         | Maximum number of avatars to display in a group (shows counter for excess).    |
| `sm`       | Boolean | `false`     | Small size variant.                                                            |
| `md`       | Boolean | `false`     | Medium size variant.                                                           |
| `lg`       | Boolean | `false`     | Large size variant.                                                            |
| `color`    | String  | `'primary'` | Color variant: primary, secondary, success, error, warning, info, or tertiary. |
| `outline`  | Boolean | `false`     | Outline style with transparent background and colored border.                  |
| `tonal`    | Boolean | `false`     | Tonal style with lighter background.                                           |
| `elevated` | Boolean | `false`     | Elevated style with shadow effect.                                             |
| `rounded`  | Boolean | `false`     | Rounded (circular) shape.                                                      |
| `square`   | Boolean | `false`     | Square shape with slight rounding (falls back to rounded if not set).          |

## ✨ Examples

```html
<template>
  <div class="flex gap-4 flex-wrap">
    <!-- Single Avatar with Image -->
    <m-avatar src="user.jpg" name="John Doe" color="primary" status="online" />

    <!-- Initials Avatar -->
    <m-avatar name="Jane Smith" color="secondary" md />

    <!-- Status Variants -->
    <m-avatar src="user2.jpg" name="Alice" color="success" status="away" lg />
    <m-avatar name="Bob" color="error" status="busy" />

    <!-- Group Avatars -->
    <m-avatar
      :avatars="['user1.jpg', 'user2.jpg', 'user3.jpg', 'user4.jpg', 'user5.jpg']"
      color="info"
      :limit="3"
      rounded
    />

    <!-- Variants -->
    <m-avatar name="Charlie" color="warning" outline />
    <m-avatar name="David" color="accent" tonal sm />
    <m-avatar src="user3.jpg" name="Eve" color="tertiary" elevated square />
  </div>
</template>

<script setup>
  import { MAvatar } from '@jotnar/m-avatar'
</script>
```

## ℹ️ Notes

- **Custom Classes**:  
  If a custom **class** attribute is provided (e.g., class="bg-blue-500 text-white"), the **color** prop is ignored, allowing your custom styles to take precedence.

- **Accessibility**:  
  The component includes **aria-label** attributes for avatars and group avatars, using the **name** prop or a default value for screen reader support.

- **Status Indicator**:  
  The **status** prop adds a colored dot (e.g., green for online, red for busy) with an optional ping animation for **online** status.

- **Group Avatars**:  
  When using the **avatars** prop, avatars are displayed in a stacked group with a counter for hidden avatars beyond the **limit**.

## 🔨 Under Construction

The homepage for this project is currently under construction. In the meantime, you can find the source code and report issues on GitHub:

- [GitHub Repository](https://github.com/JotnarDev/m-chip)
- [Report Issues](https://github.com/JotnarDev/m-chip/issues)

## ⚖️ License

MIT

## 👤 Author

Jotnar