Angular Mentionify

A standalone Angular component for a customizable, contenteditable mention input.

Angular Mentionify enables users to type mentions (e.g. @[Smith]), provides an auto-suggest dropdown, and converts mentions into non-editable spans using either a default or custom template.

---

Table of Contents

• Features
• Installation
• Usage
• API
• Comparison
• Selection & Range Reference
• Package Information
• License
• Contributers

---

Features

• Dynamic Mention Suggestions
  Filter suggestions in real-time as the user types.

• Customizable Mention Spans
  Supply a custom template function to generate the inner HTML for mentions. When provided, the default "mention" CSS class is omitted.

• UI & DB String Extraction
  Easily extract both the visible text (UI string) and the underlying stored text (DB string with mention patterns).

• Clipboard Support
  Supports paste, copy, and cut operations by converting plain text mention patterns into non-editable spans.

• Max Length Enforcement
  Automatically reverts to the last valid state if the underlying DB string exceeds the specified maximum length.

---

System Requirements

• Node.js
  It is recommended to use Node.js version 18.x or higher

• Angular
  Angular Mentionify supports Angular versions 12 to 19.
  Peer Dependencies:

  • @angular/common: >=12.0.0 <20.0.0
  • @angular/core: >=12.0.0 <20.0.0

---

Installation

Install the component via npm:

npm install angular-mentionify

Note: The package is published on npm as angular-mentionify@1.0.0.

---

Usage

Since the component is standalone, simply import it into your parent component:

// app.component.ts
import { Component } from '@angular/core';
import { AngularMentionifyComponent, MentionSuggestion } from 'angular-mentionify';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [AngularMentionifyComponent],
  template: `
    <div>
      <h2>Customizable Mention Input Demo</h2>
      <lib-angular-mentionify
        [maxLength]="30"
        [mentionSuggestions]="suggestions"
        [initialDbString]="initialDbText"
        [disabled]="isDisabled"
        [mentionTrigger]="'@'"
        [mentionWrapperLeft]="'@['"
        [mentionWrapperRight]="']'"
        [customMentionTemplate]="customTemplate"
        (uiStringChange)="onUIStringChange($event)"
        (dbStringChange)="onDBStringChange($event)"
      ></lib-angular-mentionify>
      <div style="margin-top: 20px;">
        <strong>UI String:</strong> {{ uiString }}
      </div>
      <div>
        <strong>DB String:</strong> {{ dbString }}
      </div>
    </div>
  `,
})
export class AppComponent {
  suggestions: MentionSuggestion[] = [
    { id: 1, label: 'First Name', value: 'First_Name' },
    { id: 2, label: 'Last Name', value: 'Last_Name' },
    { id: 3, label: 'Appointment Date', value: 'Appointment_Date' },
    { id: 4, label: 'Phone Number', value: 'Phone_Number' },
    { id: 5, label: 'Address', value: 'Address' },
    { id: 6, label: 'Location Phone Number', value: 'Location_Phone_Number' },
  ];

  initialDbText = 'Hello @[First_Name], how are you?';
  isDisabled: boolean = false;
  customTemplate = (suggestion: any) => {
    return `<span style="
      color: #fff;
      background: linear-gradient(270deg, #1e3c72, #2a5298, #1e3c72);
      background-size: 600% 600%;
      padding: 2px 4px;
      border-radius: 3px;
      font-weight: bold;
      display: inline-block;
    ">${suggestion.label}</span>`;
  };

  uiString: string = '';
  dbString: string = '';

  onUIStringChange(newUI: string) {
    this.uiString = newUI;
  }

  onDBStringChange(newDB: string) {
    this.dbString = newDB;
  }
}

---

API

Inputs

Property	Type	Description
maxLength	number	Maximum allowed length for the underlying DB string.
mentionSuggestions	MentionSuggestion[]	Array of suggestion objects (each containing an id and label/value).
initialDbString	string	Initial string with mention patterns (e.g. "Hello @[Smith]") to convert on initialization.
customMentionTemplate	(suggestion: MentionSuggestion) => string	Function to generate custom HTML for mention spans. If provided, the default "mention" CSS class is omitted.
disabled	boolean	Disables the input and reduces its opacity when true.
mentionTrigger	string	Character that triggers mention suggestions (e.g. @).
mentionWrapperLeft	string	Left wrapper string for DB string construction (e.g. @[ in "@[Smith]").
mentionWrapperRight	string	Right wrapper string for DB string construction (e.g. ] in "@[Smith]").

Outputs

Event	Type	Description
uiStringChange	EventEmitter<string>	Emits the current visible text (UI string) from the editor.
dbStringChange	EventEmitter<string>	Emits the underlying DB string with mention patterns (e.g. "@[Smith]").

---

Customizing Styles

Angular Mentionify comes with default styling for mention spans. You can override these styles using either of the following methods:

1. Global Style Override (Top-Level Stylesheet):
   Add CSS rules to your global stylesheet (e.g. styles.css or styles.scss) to modify the appearance of mention spans:

   .mention {
     /* Your custom styles here */
     background-color: #ffeb3b;
     color: #000;
     padding: 2px 4px;
     border-radius: 4px;
   }

2. Component-Specific Style Override (Using :host ::ng-deep):
   If you want to limit the style changes to a specific component, use the :host ::ng-deep selector in that component’s stylesheet:

   :host ::ng-deep .mention {
     /* Your component-specific styles here */
     background-color: #4caf50;
     color: #fff;
     padding: 2px 4px;
     border-radius: 4px;
   }

Alternatively, if you use the customMentionTemplate input, you can fully control the HTML and inline styling for mention spans.

---

Comparison

Angular Mentionify is designed to be modular, lightweight, and highly customizable. It offers a robust solution compared to traditional input components by focusing on dynamic suggestion filtering, custom templating, and seamless integration with Angular applications.

---

License

This project is licensed under the MIT License.

---

Contributers ✨

Angular Mentionify is crafted to bring an intuitive and customizable mention input solution to your Angular applications. Enjoy building smarter UIs with Angular Mentionify!