Angular Mention

A powerful Angular library that provides @mention functionality for text inputs and textareas. Perfect for social media apps, chat applications, or any application that needs user tagging.

Features

• 🎯 Easy Integration: Simple directive-based implementation
• 📝 Multiple Input Types: Works with <input>, <textarea>, and contenteditable elements
• 🎨 Customizable: Custom templates for suggestion items
• ⌨️ Keyboard Navigation: Full keyboard support (arrow keys, enter, escape)
• 📱 Responsive: Mobile-friendly dropdown positioning
• 🔧 Form Integration: Compatible with both Template-driven and Reactive Forms
• 🎭 TypeScript Support: Full TypeScript support with type definitions

Installation

npm install angular-mention

Quick Start

1. Import the Module

import { AngularMentionModule } from 'angular-mention';

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

2. Basic Usage

import { Component } from '@angular/core';

@Component({
  selector: 'app-example',
  template: `
    <div class="mention-container">
      <textarea
        appMention
        (mentionTriggered)="onMentionTriggered($event)"
        (mentionTextChanged)="onTextChanged($event)"
        [(ngModel)]="message"
        placeholder="Type @ to mention someone..."
        rows="4"
        cols="50">
      </textarea>
      
      <app-mention-suggestions
        [users]="filteredUsers"
        [mentionText]="currentMentionText"
        [isVisible]="showSuggestions"
        [position]="suggestionPosition"
        (userSelected)="onUserSelected($event)">
      </app-mention-suggestions>
    </div>
  `,
  styles: [`
    .mention-container {
      position: relative;
      display: inline-block;
    }
    
    textarea {
      padding: 10px;
      border: 1px solid #ccc;
      border-radius: 4px;
      font-size: 14px;
      resize: vertical;
    }
  `]
})
export class ExampleComponent {
  message = '';
  showSuggestions = false;
  currentMentionText = '';
  suggestionPosition = { top: 0, left: 0 };
  currentMentionEvent: any;

  users = [
    { id: 1, name: 'John Doe', email: '[email protected]' },
    { id: 2, name: 'Jane Smith', email: '[email protected]' },
    { id: 3, name: 'Bob Johnson', email: '[email protected]' },
    { id: 4, name: 'Alice Brown', email: '[email protected]' }
  ];

  filteredUsers = this.users;

  onMentionTriggered(event: any) {
    this.currentMentionEvent = event;
    this.currentMentionText = event.text;
    this.showSuggestions = true;
    
    // Filter users based on mention text
    this.filteredUsers = this.users.filter(user =>
      user.name.toLowerCase().includes(event.text.toLowerCase()) ||
      user.email.toLowerCase().includes(event.text.toLowerCase())
    );
  }

  onTextChanged(value: string) {
    // Handle text changes
    console.log('Text changed:', value);
  }

  onUserSelected(user: any) {
    if (this.currentMentionEvent) {
      // Get the directive instance to insert the mention
      const textarea = document.querySelector('textarea[appMention]') as HTMLTextAreaElement;
      if (textarea) {
        const currentValue = textarea.value;
        const newValue = currentValue.substring(0, this.currentMentionEvent.startIndex) +
                         '@' + user.name + ' ' +
                         currentValue.substring(this.currentMentionEvent.endIndex);
        
        this.message = newValue;
        this.showSuggestions = false;
        this.currentMentionText = '';
      }
    }
  }
}

Advanced Usage

Reactive Forms Integration

import { Component, OnInit } from '@angular/core';
import { FormBuilder, FormGroup } from '@angular/forms';

@Component({
  selector: 'app-reactive-example',
  template: `
    <form [formGroup]="commentForm">
      <textarea
        appMention
        formControlName="comment"
        (mentionTriggered)="onMentionTriggered($event)"
        placeholder="Write a comment..."
        rows="3">
      </textarea>
      
      <app-mention-suggestions
        [users]="filteredUsers"
        [mentionText]="currentMentionText"
        [isVisible]="showSuggestions"
        (userSelected)="onUserSelected($event)">
      </app-mention-suggestions>
    </form>
  `
})
export class ReactiveExampleComponent implements OnInit {
  commentForm: FormGroup;
  
  constructor(private fb: FormBuilder) {
    this.commentForm = this.fb.group({
      comment: ['']
    });
  }

  ngOnInit() {
    // Your initialization code
  }

  onMentionTriggered(event: any) {
    // Handle mention trigger
  }

  onUserSelected(user: any) {
    // Handle user selection
  }
}

Custom Templates

<app-mention-suggestions
  [users]="filteredUsers"
  [mentionText]="currentMentionText"
  [isVisible]="showSuggestions"
  (userSelected)="onUserSelected($event)">
  
  <ng-template let-user let-index="index">
    <div class="custom-user-item">
      <img [src]="user.avatar" [alt]="user.name" class="avatar">
      <div class="user-info">
        <strong>{{ user.name }}</strong>
        <small>{{ user.role }}</small>
      </div>
      <div class="user-status" [class.online]="user.isOnline"></div>
    </div>
  </ng-template>
</app-mention-suggestions>

Custom Styling

You can override the default CSS classes to customize the appearance:

.mention-suggestions {
  background: #2c3e50;
  border: 1px solid #34495e;
  border-radius: 8px;
}

.mention-suggestion-item {
  padding: 12px 16px;
  border-bottom: 1px solid #34495e;
}

.mention-suggestion-item:hover,
.mention-suggestion-item.active {
  background: #34495e;
}

.mention-suggestion-name {
  color: #ecf0f1;
  font-weight: 600;
}

.mention-suggestion-email {
  color: #95a5a6;
}

API Reference

MentionDirective

Selector: [appMention]

Inputs:

• mentionTrigger: string (default: '@') - Character that triggers mention suggestions

Outputs:

• mentionTriggered: EventEmitter<MentionEvent> - Emitted when mention is triggered
• mentionTextChanged: EventEmitter<string> - Emitted when input text changes

Methods:

• insertMention(username: string, startIndex: number, endIndex: number) - Programmatically insert a mention

MentionSuggestionsComponent

Selector: app-mention-suggestions

Inputs:

• users: User[] - Array of user objects to display
• mentionText: string - Current mention text for filtering
• isVisible: boolean - Controls visibility of suggestions
• position: {top: number, left: number} - Position of dropdown
• maxHeight: number (default: 200) - Maximum height of suggestions list
• customTemplate: TemplateRef - Custom template for suggestion items

Outputs:

• userSelected: EventEmitter<User> - Emitted when user is selected

User Interface

interface User {
  id: string | number;
  name: string;
  avatar?: string;
  email?: string;
  // Add any additional properties you need
}

MentionEvent Interface

interface MentionEvent {
  text: string;
  startIndex: number;
  endIndex: number;
}

Building the Library

# Build the library
ng build angular-mention

# Run tests
ng test angular-mention

# Run e2e tests
ng e2e angular-mention

Publishing to NPM

# Navigate to the dist directory
cd dist/angular-mention

# Publish to npm
npm publish

Browser Support

This library supports all modern browsers:

• Chrome 60+
• Firefox 55+
• Safari 12+
• Edge 79+

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Changelog

v1.0.0

• Initial release
• Basic mention functionality
• Support for input and textarea elements
• Customizable suggestion templates
• Keyboard navigation
• Form integration support