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 [email protected].

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!