@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:

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):

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):

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

Once these steps are complete, you can use the component anywhere in your app.

📦 Local Registration

Import and use the component in specific components:

<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

<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
• Report Issues

⚖️ License

MIT

👤 Author

Jotnar