DOCSEARCHbyAlgolia
Submit Docs

textcomplete

repository·main·Indexed 23 days ago

https://github.com/yuku/textcomplete

A modular autocomplete library providing suggestion functionality for various text input types. It includes a core engine (@textcomplete/core) with specialized adapters for HTMLTextAreaElement (@textcomplete/textarea), contenteditable elements (@textcomplete/contenteditable), and CodeMirror editors (@textcomplete/codemirror). The library also provides a legacy jQuery plugin (jquery-textcomplete) compatible with jQuery 1.7.0+ and Zepto 1.0+.

Tokens
12.9K
Snippets
29
Records
83
Agent score
82%

What's inside textcomplete

  1. Overview of @textcomplete/core

    main

    The @textcomplete/core package serves as the central engine for the Textcomplete library. It provides the core logic required for text completion functionality, which is then extended by specialized packages for different input types (such as @textcomplete/textarea, @textcomplete/codemirror, or @textcomplete/contenteditable).

    For live demonstrations and more detailed documentation, visit the official site: yuku.takahashi.coffee/textcomplete.

  2. Overview of Textcomplete packages

    main

    Textcomplete provides autocomplete functionality for various HTML elements. It is modularized into several subpackages depending on the target editor type:

    • @textcomplete/core: The core logic of Textcomplete.
    • @textcomplete/textarea: Specifically for HTMLTextAreaElement editors.
    • @textcomplete/contenteditable: For contenteditable elements (Experimental).
    • @textcomplete/codemirror: For CodeMirror editors (Experimental).
    • @textcomplete/utils: Utility functions used by the editors.

  3. Implement the Editor abstract class for custom targets

    main

    To support a new type of input (like a custom code editor), you must extend the Editor abstract class. The Editor class handles event emission and provides helpers for interacting with the input area.

    Required Implementations:

    • applySearchResult(result: SearchResult): Called when a user selects a result. Use this to update the editor's content.
    • getCursorOffset(): CursorOffset: Returns the absolute coordinates of the input cursor relative to the window.
    • getBeforeCursor(): string | null: Returns the text from the start of the input up to the cursor. Returns null if the selection is a range rather than a single cursor position.

    Required Event Emissions: Your implementation must trigger these methods at the appropriate times during user interaction:

    • emitMoveEvent(code: "UP" | "DOWN"): Moves the active dropdown item.
    • emitEnterEvent(): Selects the current search result.
    • emitChangeEvent(): Triggers the auto-completion process.
    • emitEscEvent(): Hides the dropdown.

  4. Understand Textcomplete custom event patterns

    main

    Textcomplete uses a consistent naming convention for its custom events based on the lifecycle of an action. Events generally come in pairs:

    1. Infinitive form (e.g., show): Triggered at the start of an action. These events support preventDefault(), allowing you to intercept and stop the action before it executes.
    2. Past participle form (e.g., shown): Triggered upon the completion of an action. These events wait for CSS transitions to finish before firing.

    Use the infinitive events if you need to implement logic that can cancel a UI change (like preventing the dropdown from appearing).

  5. Initialize Textcomplete with a Textarea editor

    main

    The Textcomplete class acts as the central mediator. To use it, you must provide an editor instance (such as Textarea) and an optional TextcompleteOptions object.

    • editor: An instance of an editor (e.g., Textarea) that encapsulates the target HTMLTextAreaElement.
    • options: An optional configuration object. Currently supports a dropdown property of type DropdownOptions.

  6. Quickstart: Implement autocomplete with Textarea

    main

    To implement autocomplete, follow these three steps:

    1. Create an editor object: Encapsulate an HTML element (like a <textarea>) using the Textarea editor.
    2. Initialize Textcomplete: Create a new Textcomplete instance by passing the editor and an optional Textcomplete~Options object.
    3. Register strategies: Provide an array of Strategy~Properties to define how text is matched, searched, and replaced.

    Note: You can pass an index property to a strategy to specify which match group from the match regex should be used as the query. The default value is 2.

    // 1. Create the editor
var textareaElement = document.getElementById('your-textarea-element')
var editor = new Textarea(textareaElement);

// 2. Initialize Textcomplete
var textcomplete = new Textcomplete(editor, {
  dropdown: {
    maxCount: Infinity
  }
});

// 3. Register strategies
textcomplete.register([{
  // Emoji strategy
  match: /(^|\s):(\w+)$/,
  search: function (term, callback) {
    callback(emojies.filter(emoji => { return emoji.startsWith(term); }));
  },
  replace: function (value) {
    return '$1:' + value + ': ';
  }
}]);

  8. Style the jquery-textcomplete dropdown

    main

    The HTML generated by jquery-textcomplete is designed to be compatible with Bootstrap's dropdown component, meaning you can use Bootstrap CSS files directly for styling.

    If you are not using Bootstrap, you can style the dropdown by targeting the following HTML structure:

    • The main container uses the class .textcomplete-dropdown.
    • Each suggestion item uses the class .textcomplete-item on an <li> element.
    • The currently selected item uses the class .textcomplete-item.active.
    • The content inside the <a> tags is determined by your templateFunc.

  11. Change the trigger token in a strategy

    main

    To change the trigger character (e.g., using @ instead of the default :), define match and replace properties within your strategy object.

    If you want to keep the trigger character in the text after selection, use a replace function that includes the trigger. If you want to remove the trigger character when a user makes a choice, use a replace function that excludes it.