autolinker vs linkify-html vs linkify-it vs linkify-string vs linkifyjs vs url-regex
Automating URL Detection and Link Generation in JavaScript
Search packages..
autolinkerlinkify-htmllinkify-itlinkify-stringlinkifyjsurl-regexSimilar Packages:

Automating URL Detection and Link Generation in JavaScript

These libraries solve the common problem of converting plain text URLs into clickable hyperlinks, but they approach the task with different levels of abstraction and safety. autolinker is a high-level, all-in-one solution that handles parsing, HTML generation, and sanitization automatically. The linkifyjs ecosystem (linkify-it, linkify-string, linkify-html) offers a modular approach where you can choose between a low-level parser, a string replacer, or a full HTML processor. url-regex is a foundational utility that provides only the regular expression pattern for URL detection, requiring you to build the linking logic yourself. Choosing the right tool depends on whether you need a quick drop-in fix, granular control over the parsing logic, or just the raw pattern for custom validation.

Npm Package Weekly Downloads Trend

3 Years

Github Stars Ranking

Stat Detail

Package
Downloads
Stars
Size
Issues
Publish
License
autolinker01,4962.44 MB66a year agoMIT
linkify-html02,039131 kB504 months agoMIT
linkify-it0739149 kB32 months agoMIT
linkify-string02,0399.75 kB504 months agoMIT
linkifyjs02,039259 kB504 months agoMIT
url-regex0354-207 years agoMIT

Automating URL Detection and Link Generation: A Deep Dive into JavaScript Libraries

Turning plain text URLs into clickable links seems simple until you encounter edge cases like trailing punctuation, complex query parameters, or existing HTML tags. The JavaScript ecosystem offers several tools for this, ranging from "batteries-included" processors to raw regular expression utilities. Let's compare how autolinker, the linkifyjs family (linkify-it, linkify-string, linkify-html), and url-regex handle real-world engineering challenges.

πŸ›‘οΈ Security and HTML Safety: Built-in vs. DIY

The biggest risk in auto-linking is Cross-Site Scripting (XSS). If you blindly replace text with <a> tags, you might accidentally break existing HTML or inject malicious scripts.

autolinker prioritizes safety by default. It parses the input, identifies text nodes, and only injects links where safe. It automatically escapes HTML characters in the surrounding text.

import Autolinker from 'autolinker';

const input = 'Check this out: <script>alert("xss")</script> and http://example.com';
const result = Autolinker.link(input);

// Output: "Check this out: &lt;script&gt;alert("xss")&lt;/script&gt; and <a href="http://example.com">example.com</a>"
// The script tag is escaped, preventing execution.

linkify-html (part of the linkifyjs ecosystem) is designed specifically to process strings that already contain HTML. It walks the HTML tree and adds links only to text nodes, leaving existing tags untouched.

import linkifyHtml from 'linkify-html';

const input = 'Visit <b>http://example.com</b> for more';
const result = linkifyHtml(input);

// Output: "Visit <b><a href="http://example.com">http://example.com</a></b> for more"
// Existing <b> tags are preserved; links are injected inside them safely.

url-regex provides zero safety. It only gives you a pattern. If you use it to replace strings naively, you are responsible for escaping HTML and preventing XSS.

import urlRegex from 'url-regex';

const input = 'Go to http://example.com and <script>bad()</script>';
const regex = urlRegex();

// Dangerous: You must manually handle HTML escaping and replacement logic
const result = input.replace(regex, (url) => `<a href="${url}">${url}</a>`);
// If input contained HTML entities or existing tags, this approach could break them.

βš™οΈ Customization: Protocols and Validation Rules

Sometimes standard HTTP/HTTPS links aren't enough. You might need to support custom protocols like myapp:// or exclude specific domains.

linkify-it shines here. It is a low-level parser that lets you define custom schemas and validation logic before any HTML is generated.

import LinkifyIt from 'linkify-it';

const linkify = LinkifyIt();
// Add a custom protocol
linkify.add('myapp:', {
  validate: (text, pos, self) => {
    // Custom validation logic
    return true;
  }
});

const matches = linkify.match('Open myapp://settings');
// Returns match objects with detailed info, not HTML

autolinker allows some customization via its configuration object, such as replacing the default link handler, but it is less flexible than linkify-it for defining entirely new protocol rules from scratch.

import Autolinker from 'autolinker';

const result = Autolinker.link('Check http://example.com', {
  replaceFn: (match) => {
    // Intercept specific matches
    if (match.getType() === 'url' && match.getUrl().includes('ads')) {
      return false; // Don't link this
    }
  }
});

url-regex allows you to pass options to tweak the regex (like including or excluding specific parts), but you cannot easily add entirely new protocol logic without modifying the regex pattern itself, which is fragile.

import urlRegex from 'url-regex';

// Strict mode excludes some edge cases
const strictRegex = urlRegex({ strict: true });
// You cannot easily add "myapp:" support without rewriting the pattern

πŸ“¦ Output Format: HTML vs. Data vs. Pattern

What do you get back after processing? The return type dictates your next steps.

autolinker and linkify-html / linkify-string return processed strings ready for insertion into the DOM.

// autolinker
const html = Autolinker.link('Go to google.com');
// Returns: 'Go to <a href="http://google.com">google.com</a>'

// linkify-string
import linkifyStr from 'linkify-string';
const htmlStr = linkifyStr('Go to google.com');
// Returns: 'Go to <a href="http://google.com">google.com</a>'

linkify-it returns an array of match objects. This is powerful if you need to render links in a non-HTML environment (like React Native, Flutter, or a custom virtual DOM) where you need structured data instead of a string.

import LinkifyIt from 'linkify-it';
const linkify = LinkifyIt();
const matches = linkify.match('Visit google.com and foo@bar.com');

// Returns: [
//   { type: 'link', url: 'http://google.com', text: 'google.com', index: 6, ... },
//   { type: 'email', url: 'mailto:foo@bar.com', text: 'foo@bar.com', index: 21, ... }
// ]

url-regex returns a RegExp object. You use it with standard string methods like .match() or .replace().

import urlRegex from 'url-regex';
const matches = 'Visit http://a.com and http://b.com'.match(urlRegex());
// Returns: ['http://a.com', 'http://b.com']

🧩 Handling Existing HTML: The Broken Tag Problem

If your input string already contains HTML tags, simple regex replacement often breaks the markup.

linkify-html is explicitly built for this. It parses the HTML structure and avoids injecting links inside attribute values or existing tags.

import linkifyHtml from 'linkify-html';

const input = '<a href="http://existing.com">Link</a> and http://new.com';
const result = linkifyHtml(input);
// Output: '<a href="http://existing.com">Link</a> and <a href="http://new.com">http://new.com</a>'
// The existing link is untouched.

autolinker also handles this well by default, detecting existing anchors and skipping them unless configured otherwise.

import Autolinker from 'autolinker';

const input = '<a href="http://existing.com">Link</a> and http://new.com';
const result = Autolinker.link(input);
// Output: Similar safe result, preserving the existing anchor tag.

url-regex and linkify-string (when used on raw HTML strings) will blindly replace text anywhere, potentially breaking attributes.

import linkifyStr from 'linkify-string';

const input = '<img src="http://image.com">';
const result = linkifyStr(input); 
// DANGER: Might turn into '<img src="<a href="http://image.com">http://image.com</a>">'
// This breaks the image tag completely.

πŸš€ Performance and Bundle Strategy

For high-volume text processing (e.g., rendering thousands of comments), the overhead of a full HTML parser matters.

  • url-regex is the lightest. It's just a pattern. No parsing logic, no DOM simulation. Best for simple validation or extraction where speed is critical and safety is handled elsewhere.
  • linkify-it is highly optimized for parsing speed. It compiles its rules into a finite state machine, making it faster than naive regex loops for complex text.
  • autolinker and linkify-html carry more weight because they include HTML parsing and sanitization logic. Use them when correctness and security outweigh raw cycle count.

πŸ“Š Summary: Which Tool Fits Your Architecture?

Featureautolinkerlinkify-htmllinkify-itlinkify-stringurl-regex
Primary InputPlain Text or HTMLHTML StringPlain TextPlain TextPlain Text
OutputSafe HTML StringSafe HTML StringMatch ObjectsHTML StringRegExp Pattern
XSS Protectionβœ… Built-inβœ… Built-in❌ (Data only)⚠️ (Text only)❌ (None)
Custom Protocols⚠️ Limited⚠️ Via Engineβœ… Full Control⚠️ Via Engine❌ Hard
Preserves HTMLβœ… Yesβœ… YesN/A❌ No❌ No
Best ForDrop-in SafetyHTML Rich TextCustom RenderersSimple TextValidation

πŸ’‘ Final Recommendation

If you are building a user-facing content platform (blogs, comments, chats) where security is non-negotiable, reach for autolinker. It solves the hardest problems (XSS, existing tags, email detection) with a single function call.

If you are working in a React/Vue ecosystem where you receive rich HTML from a CMS and need to inject links without breaking the layout, linkify-html is the precise tool for the job.

If you are building a custom UI component (like a rich text editor or a mobile app) where you need to know where the links are rather than just getting an HTML string, use linkify-it to get the structured data and render it yourself.

Avoid url-regex for linking tasks unless you are building a validator or a log parser. Re-implementing the linking and sanitization logic yourself is a common source of security bugs in modern web applications.

How to Choose: autolinker vs linkify-html vs linkify-it vs linkify-string vs linkifyjs vs url-regex

  • autolinker:

    Choose autolinker if you need a robust, zero-config solution that safely converts text to HTML links while handling edge cases like email addresses and phone numbers out of the box. It is ideal for content management systems, comment sections, or chat interfaces where security (XSS prevention) and ease of use are top priorities. Avoid it if you need to customize the underlying URL parsing logic deeply, as it abstracts most of that away.

  • linkify-html:

    Choose linkify-html if you are already using the linkifyjs ecosystem and specifically need to process HTML strings without breaking existing tags. It is the direct counterpart to autolinker but relies on the linkify-it parser engine. This is best for scenarios where you receive raw HTML from a backend and need to inject links into text nodes safely without re-parsing the entire document structure manually.

  • linkify-it:

    Choose linkify-it if you need maximum control over the URL detection rules, such as adding support for custom protocols (e.g., myapp://) or tweaking validation logic. It is a low-level parser that returns match objects rather than generating HTML, making it perfect for building custom renderers or integrating link detection into non-HTML environments like mobile apps or desktop clients.

  • linkify-string:

    Choose linkify-string if your input is plain text and you want a simple function to return a new string with HTML anchor tags injected. It sits between the low-level parser and the full HTML processor, offering a balance of simplicity and customization via the linkifyjs engine. Use this for lightweight text processing tasks where you don't need the overhead of a full HTML parser but still want reliable URL detection.

  • linkifyjs:

    Choose linkifyjs as the umbrella package if you want a unified entry point that exports the core engine and commonly used helpers together. It is suitable for projects that might evolve from simple string replacement to complex custom parsing, allowing you to import specific sub-modules later without changing dependencies. It ensures version consistency across the linkify-it, linkify-string, and linkify-html components.

  • url-regex:

    Choose url-regex only if you need a standalone regular expression pattern for validation or extraction without any linking or HTML generation logic. It is useful for form validation, log parsing, or scenarios where you need to detect URLs in environments where executing linking logic is unnecessary. Be aware that using this requires you to implement your own replacement and sanitization logic, which increases the risk of security vulnerabilities if not handled carefully.

Similar Npm Packages to linkify-it

linkify-it is a powerful library for parsing and linking URLs, emails, and other types of links in text. It provides a flexible and efficient way to convert plain text into clickable links, making it particularly useful for applications that require user-generated content or chat interfaces. With its customizable options, linkify-it allows developers to define their own rules for what constitutes a link, ensuring that the library can be tailored to fit specific needs.

While linkify-it is a robust solution for link parsing, there are several alternatives available in the ecosystem that offer similar functionalities. Here are a few noteworthy options:

  • autolinker is a library designed to automatically convert URLs, email addresses, and hashtags into clickable links. It is easy to use and provides a straightforward API for developers. Autolinker is particularly useful for applications that require quick and simple linkification without the need for extensive customization.
  • linkify-html is a library that transforms plain text into HTML with clickable links. It is built on top of linkify-it and provides additional functionality for generating HTML output. If you need to convert text into HTML while ensuring that links are properly formatted, linkify-html is a great choice.
  • linkify-string is a lightweight library that focuses on converting strings into linkified text. It is designed for simplicity and ease of use, making it ideal for projects that require basic linkification without the overhead of more complex libraries.
  • linkifyjs is another versatile library for linkifying text. It offers a range of features, including customizable link patterns and the ability to handle various types of links. Linkifyjs is suitable for applications that require more advanced link parsing capabilities.
  • url-regex-safe is a library that provides a safe and reliable way to match URLs in strings using regular expressions. While it does not perform linkification directly, it can be used in conjunction with other libraries to identify URLs that need to be converted into links.

To explore how linkify-it compares with these alternatives, check out the comparison: Comparing autolinker vs linkify-html vs linkify-it vs linkify-string vs linkifyjs vs url-regex-safe.

Similar Npm Packages to linkifyjs

linkifyjs is a JavaScript library designed to convert plain text URLs, email addresses, and other types of links into clickable hyperlinks. This library is particularly useful for applications that need to process user-generated content, such as chat applications, forums, or comment sections, where users may include links in their messages. By automatically detecting and converting these links, linkifyjs enhances user experience and interaction.

While linkifyjs is a robust solution for linkification, there are several alternatives in the ecosystem that offer similar functionalities. Here are a few noteworthy options:

  • autolinker is a library that automatically converts URLs, email addresses, and hashtags into clickable links. It is highly customizable, allowing developers to specify how links should be formatted and styled. Autolinker is a great choice if you need a straightforward solution that provides flexibility in how links are rendered in your application.
  • linkify-html is a library that converts plain text into HTML with clickable links. It supports various link types, including URLs, email addresses, and hashtags, and allows for customization of link attributes and styles. If you are working with HTML content and need a solution that integrates seamlessly with your existing HTML structure, linkify-html is an excellent option.
  • linkify-it is a powerful and flexible library for linkifying text. It supports a wide range of link types and offers a customizable syntax for detecting links. Linkify-it is particularly useful for developers who need fine-grained control over the link detection process and want to extend or modify the default behavior.
  • linkify-string is a simple library that focuses on converting plain text into a string with clickable links. It is lightweight and easy to use, making it suitable for projects that require basic linkification without additional complexity. If you need a straightforward solution for linkifying strings, linkify-string is a good choice.
  • url-regex is a library that provides a regular expression for matching URLs in strings. While it does not convert text into clickable links directly, it can be used in conjunction with other libraries to identify and process URLs. If you prefer to handle linkification manually or need to extract URLs for further processing, url-regex can be a useful tool.

To see how linkifyjs compares with these alternatives, check out the comparison: Comparing autolinker vs linkify-html vs linkify-it vs linkify-string vs linkifyjs vs url-regex.

README for autolinker

Autolinker.js

version NPM Downloads build codecov GitHub License

Automatic linking of URLs, emails, phone numbers, mentions, and hashtags in text.

Input:  "Visit google.com" 
         
               |
               |
               v

Output: "Visit <a href="https://google.com">google.com</a>"

Because I had so much trouble finding a good auto-linking implementation out in the wild, I decided to roll my own. It seemed that everything I found was either an implementation that didn't cover every case, had many false positives linked, or was just limited in one way or another.

So, this utility attempts to handle everything. It:

  • Autolinks URLs, whether or not they start with the protocol (i.e. 'http://'). In other words, it will automatically link the text "google.com", as well as "http://google.com". Will also autolink IPv4 addresses.
  • Will properly handle URLs with query params, anchors, and special characters, and not include chars like a trailing . at the end of a sentence, or a ) char if the URL is inside parenenthesis.
  • Will autolink email addresses
  • Will autolink phone numbers
  • Will autolink mentions (Twitter, Instagram, Soundcloud, TikTok, Youtube)
  • Will autolink hashtags (Twitter, Instagram, Facebook, TikTok, Youtube)
  • Won't clobber URLs with hash anchors by treating them as hashtags (like some other libraries do). For example: google.com/#anchor is properly linked.
  • Will properly handle HTML input. The utility will not overwrite an href attribute inside anchor (<a>) tags (or any other tag/attribute), and will not accidentally wrap the inner text of <a>/<script>/<style> tags with a new one (which cause doubly-nested anchor tags, or mess with scripts)
  • Will do all of this in O(n) (linear) time with low constant factors and without the possibility of RegExp Catastrophic Backtracking, making it extremely fast and unsusceptible to pathological inputs.

Quick benchmarks comparison:

LibraryOps/SecMOECompared to Fastest
Autolinker@4.1.53,278Β±0.40%Fastest βœ…
anchorme@3.0.82,393Β±0.35%26% (1.37x) slower
linkifyjs@4.2.0 (linkify-html)1,875Β±0.32%42% (1.75x) slower
linkify-it@5.0.0491Β±0.54%85% (6.67x) slower

(please let me know of other comparable libraries to compare to!)

Hope that this utility helps you as well!

Full API Docs: http://gregjacobs.github.io/Autolinker.js/api/
Live Example: http://gregjacobs.github.io/Autolinker.js/examples/live-example/

Upgrading from a previous major version of Autolinker?

See Breaking Changes at the bottom of this readme.

Installation

Installing with npm:

npm install autolinker --save

Installing with Yarn:

yarn add autolinker

Installing with pnpm:

pnpm add autolinker

Installing with Bower:

bower install Autolinker.js --save

Direct download

Simply clone this repository or download a zip of the project, and link to either dist/Autolinker.js or dist/Autolinker.min.js with a <script> tag.

Importing Autolinker

ES6+/TypeScript/Webpack/Node.js ESM:

import Autolinker from 'autolinker';

Node.js CommonJS:

const Autolinker = require('autolinker');
// note: npm wants an all-lowercase package name, but the utility is a class and
// should be aliased with a capital letter

Browser

<!-- 'Autolinker.js' or 'Autolinker.min.js' - non-minified is better for 
     debugging, minified is better for users' download time -->
<script src="path/to/autolinker/dist/Autolinker.min.js"></script>

Usage

Using the static link() method:

const linkedText = Autolinker.link(textToAutolink[, options]);

Using as a class:

const autolinker = new Autolinker([ options ]);

const linkedText = autolinker.link(textToAutoLink);

Note: if using the same options to autolink multiple pieces of html/text, it's slightly more efficient to create a single Autolinker instance, and run the link() method repeatedly (i.e. use the "class" form above).

Examples:

const linkedText = Autolinker.link("Check out google.com");
// Produces: "Check out <a href="http://google.com" target="_blank" rel="noopener noreferrer">google.com</a>"

const linkedText = Autolinker.link("Check out google.com", { 
    newWindow: false 
});
// Produces: "Check out <a href="http://google.com">google.com</a>"

Options

The following are the options which may be specified for linking. These are specified by providing an Object as the second parameter to Autolinker.link(). These include:

  • newWindow : boolean
    true to have the links should open in a new window when clicked, false otherwise. Defaults to true.

  • urls : boolean/Object
    true to have URLs auto-linked, false to skip auto-linking of URLs. Defaults to true.

    This option also accepts an Object form with 3 properties to allow for more customization of what exactly gets linked. All default to true:

    • schemeMatches (boolean): true to match URLs found prefixed with a scheme, i.e. http://google.com, or other+scheme://google.com, false to prevent these types of matches.
    • tldMatches: true to match URLs with known top level domains (.com, .net, etc.) that are not prefixed with a scheme (i.e. 'http://'). Ex: google.com, asdf.org/?page=1, etc. Set to false to prevent these types of matches.
    • ipV4Matches (boolean): true to match IPv4 addresses. Ex: 192.168.0.1. false to prevent these types of matches. Note that if the IP address had a prefixed scheme (such as 'http://'), and schemeMatches is true, it will still be linked.

    Example usage: urls: { schemeMatches: true, tldMatches: false, ipV4Matches: true }

  • email : boolean
    true to have email addresses auto-linked, false to skip auto-linking of email addresses. Defaults to true.

  • phone : boolean
    true to have phone numbers auto-linked, false to skip auto-linking of phone numbers. Defaults to true.

  • mention : string
    A string for the service name to have mentions (@username) auto-linked to. Supported values at this time are 'twitter', 'soundcloud', 'instagram', 'tiktok', and 'youtube'. Pass false to skip auto-linking of mentions. Defaults to false.

  • hashtag : boolean/string
    A string for the service name to have hashtags auto-linked to. Supported values at this time are 'twitter', 'facebook', 'instagram', 'tiktok', and 'youtube'. Pass false to skip auto-linking of hashtags. Defaults to false.

  • stripPrefix : boolean
    true to have the 'http://' (or 'https://') and/or the 'www.' stripped from the beginning of displayed links, false otherwise. Defaults to true.

    This option also accepts an Object form with 2 properties to allow for more customization of what exactly is prevented from being displayed. Both default to true:

    • scheme (boolean): true to prevent the scheme part of a URL match from being displayed to the user. Example: 'http://google.com' will be displayed as 'google.com'. false to not strip the scheme. NOTE: Only an 'http://' or 'https://' scheme will be removed, so as not to remove a potentially dangerous scheme (such as 'file://' or 'javascript:').
    • www (boolean): true to prevent the 'www.' part of a URL match from being displayed to the user. Ex: 'www.google.com' will be displayed as 'google.com'. false to not strip the 'www'.

  • stripTrailingSlash : boolean
    true to remove the trailing slash from URL matches, false to keep the trailing slash. Example when true: http://google.com/ will be displayed as http://google.com. Defaults to true.

  • truncate : number/Object
    A number for how many characters long URLs/emails/Twitter handles/Twitter hashtags should be truncated to inside the text of a link. If the match is over the number of characters, it will be truncated to this length by replacing the end of the string with a two period ellipsis ('..').

    Example: a url like 'http://www.yahoo.com/some/long/path/to/a/file' truncated to 25 characters may look like this: 'yahoo.com/some/long/pat..'

    In the object form, both length and location may be specified to perform truncation. Available options for location are: 'end' (default), 'middle', or 'smart'. Example usage:

    truncate: { length: 32, location: 'middle' }

    The 'smart' truncation option is for URLs where the algorithm attempts to strip out unnecessary parts of the URL (such as the 'www.', then URL scheme, hash, etc.) before trying to find a good point to insert the ellipsis if it is still too long. For details, see source code of: TruncateSmart

  • className : string
    A CSS class name to add to the generated anchor tags. This class will be added to all links, as well as this class plus "url"/"email"/"phone"/"hashtag"/"mention" suffixes for styling url/email/phone/hashtag/mention links differently.

    The name of the hashtag/mention service is also added as a CSS class for those types of matches.

    For example, if this config is provided as "my-link", then:

    • URL links will have the CSS classes: "my-link my-link-url"
    • Email links will have the CSS classes: "my-link my-link-email"
    • Phone links will have the CSS classes: "my-link my-link-phone"
    • Twitter mention links will have the CSS classes: "my-link my-link-mention my-link-twitter"
    • Instagram mention links will have the CSS classes: "my-link my-link-mention my-link-instagram"
    • Hashtag links will have the CSS classes: "my-link my-link-hashtag my-link-twitter"

  • decodePercentEncoding: boolean
    true to decode percent-encoded characters in URL matches, false to keep the percent-encoded characters.

    Example when true: https://en.wikipedia.org/wiki/San_Jos%C3%A9 will be displayed as https://en.wikipedia.org/wiki/San_JosΓ©.

    Defaults to true.

  • replaceFn : Function
    A function to use to programmatically make replacements of matches in the input string, one at a time. See the section Custom Replacement Function for more details.

  • sanitizeHtml : boolean

    true to HTML-encode the start and end brackets of existing HTML tags found in the input string. This will escape < and > characters to &lt; and &gt;, respectively.

    Setting this to true will prevent XSS (Cross-site Scripting) attacks, but will remove the significance of existing HTML tags in the input string. If you would like to maintain the significance of existing HTML tags while also making the output HTML string safe, leave this option as false and use a tool like https://github.com/cure53/DOMPurify (or others) on the input string before running Autolinker.

    Defaults to false.

For example, if you wanted to disable links from opening in new windows, you could do:

const linkedText = Autolinker.link("Check out google.com", { 
    newWindow: false 
});
// Produces: "Check out <a href="http://google.com">google.com</a>"

And if you wanted to truncate the length of URLs (while also not opening in a new window), you could do:

const linkedText = Autolinker.link("http://www.yahoo.com/some/long/path/to/a/file", { 
    truncate: 25, 
    newWindow: false 
});
// Produces: "<a href="http://www.yahoo.com/some/long/path/to/a/file">yahoo.com/some/long/pat..</a>"

More Examples

One could update an entire DOM element that has unlinked text to auto-link them as such:

const myTextEl = document.getElementById('text');
myTextEl.innerHTML = Autolinker.link(myTextEl.innerHTML);

Using the same pre-configured Autolinker instance in multiple locations of a codebase (usually by dependency injection):

const autolinker = new Autolinker({ newWindow: false, truncate: 25 });

//...

autolinker.link("Check out http://www.yahoo.com/some/long/path/to/a/file");
// Produces: "Check out <a href="http://www.yahoo.com/some/long/path/to/a/file">yahoo.com/some/long/pat..</a>"

//...

autolinker.link( "Go to www.google.com" );
// Produces: "Go to <a href="http://www.google.com">google.com</a>"

Retrieving the List of Matches

If you're just interested in retrieving the list of Matches without producing a transformed string, you can use the parse() method.

For example:

const matches = Autolinker.parse("Hello google.com, I am asdf@asdf.com", {
    urls: true,
    email: true
});

console.log(matches.length);         // 2
console.log(matches[0].type);        // 'url'
console.log(matches[0].getUrl());    // 'google.com'
console.log(matches[1].type);        // 'email'
console.log(matches[1].getEmail());  // 'asdf@asdf.com'

Custom Replacement Function

A custom replacement function (replaceFn) may be provided to replace url/email/phone/mention/hashtag matches on an individual basis, based on the return from this function.

Full example, for purposes of documenting the API:

const input = "...";  // string with URLs, Email Addresses, Mentions (Twitter, Instagram), and Hashtags

const linkedText = Autolinker.link(input, {
    replaceFn : function(match) {
        console.log("href = ", match.getAnchorHref());
        console.log("text = ", match.getAnchorText());

        switch(match.type) {
            case 'url':
                console.log("url: ", match.getUrl());

                return true;  // let Autolinker perform its normal anchor tag replacement

            case 'email':
                const email = match.getEmail();
                console.log("email: ", email);

                if(email === "my@own.address") {
                    return false;  // don't auto-link this particular email address; leave as-is
                } else {
                    return;  // no return value will have Autolinker perform its normal anchor tag replacement (same as returning `true`)
                }

            case 'phone':
                console.log("Phone Number: ", match.getPhoneNumber());

                return '<a href="http://newplace.to.link.phone.numbers.to/">' + match.getPhoneNumber() + '</a>';

            case 'mention':
                console.log("Mention: ", match.getMention());
                console.log("Mention Service Name: ", match.getServiceName());

                return '<a href="http://newplace.to.link.mention.handles.to/">' + match.getMention() + '</a>';

            case 'hashtag':
                console.log("Hashtag: ", match.getHashtag());

                return '<a href="http://newplace.to.link.hashtag.handles.to/">' + match.getHashtag() + '</a>';
        }
    }
} );

Modifying the default generated anchor tag

const input = "...";  // string with URLs, Email Addresses, Mentions (Twitter, Instagram), and Hashtags

const linkedText = Autolinker.link( input, {
    replaceFn : function( match ) {
        console.log("href = ", match.getAnchorHref());
        console.log("text = ", match.getAnchorText());

        const tag = match.buildTag();       // returns an `Autolinker.HtmlTag` instance for an <a> tag
        tag.setAttr('rel', 'nofollow');   // adds a 'rel' attribute
        tag.addClass('external-link');    // adds a CSS class
        tag.setInnerHtml('Click here!');  // sets the inner html for the anchor tag

        return tag;
    }
} );

The replaceFn is provided one argument:

  1. An Autolinker.match.Match object which details the match that is to be replaced.

A replacement of the match is made based on the return value of the function. The following return values may be provided:

  1. No return value (undefined), or true (boolean): Delegate back to Autolinker to replace the match as it normally would.
  2. false (boolean): Do not replace the current match at all - leave as-is.
  3. Any string: If a string is returned from the function, the string will be used directly as the replacement HTML for the match.
  4. An Autolinker.HtmlTag instance, which can be used to build/modify an HTML tag before writing out its HTML text.

Full API Docs

The full API docs for Autolinker may be referenced at: http://gregjacobs.github.io/Autolinker.js/api/

Live Example

http://gregjacobs.github.io/Autolinker.js/examples/

Upgrading from v3.x -> v4.x (Breaking Changes)

  1. Internet Explorer support has been removed since its official demise in June 2022.
  2. The urls.wwwMatches config has been removed. A www. prefix is now treated like any other subdomain of a top level domain (TLD) match (such as 'subdomain.google.com').
  3. Match.getType() should be replaced with Match.type. This allows for TypeScript type narrowing of Match objects returned by the parse() method or inside the replaceFn.
  4. The Matcher classes have been removed in favor of a single finite state machine parser, greatly improving the performance of Autolinker (3x performance improvement over the 3.x branch), but removing some of the customizability of the old regular expressions. Will address this customizability in a future release.
  5. Autolinker.AnchorTagBuilder, Autolinker.HtmlTag, and Autolinker.match.* references have been removed. These shouldn't be needed as public APIs, but please raise a GitHub issue if these are for some reason needed.

Upgrading from v2.x -> v3.x (Breaking Changes)

  1. If you are still on v1.x, first follow the instructions in the Upgrading from v1.x -> v2.x section below.
  2. The HtmlParser class has been removed in favor of an internal parseHtml() function which replaces the old regexp-based implementation with a state machine parser that is guaranteed to run in linear time. If you were using the HtmlParser class directly, I recommend switching to htmlparser2, which implements the HTML semantics better. The internal parseHtml() function that Autolinker now uses is fairly geared towards Autolinker's purposes, and may not be useful in a general HTML parsing sense.

Upgrading from v1.x -> v2.x (Breaking Changes)

  1. If you are still on v0.x, first follow the instructions in the Upgrading from v0.x -> v1.x section below.

  2. The codebase has been converted to TypeScript, and uses ES6 exports. You can now use the import statement to pull in the Autolinker class and related entities such as Match:

    // ES6/TypeScript/Webpack
import Autolinker, { Match } from 'autolinker';

    The require() interface is still supported as well for Node.js:

    // Node.js
const Autolinker = require('autolinker');

  3. You will no longer need the @types/autolinker package as this package now exports its own types

  4. You will no longer be able to override the regular expressions in the Matcher classes by assigning to the prototype (for instance, something like PhoneMatcher.prototype.regex = ...). This is due to how TypeScript creates properties for class instances in the constructor rather than on prototypes.

    The idea of providing your own regular expression for these classes is a brittle notion anyway, as the Matcher classes rely on capturing groups in the RegExp being in the right place, or even multiple capturing groups for the same piece of information to support a different format. These capturing groups and associated code are subject to change as the regular expression needs to be updated, and will not involve a major version release of Autolinker.

    In the future you will be able to override the default Matcher classes entirely to provide your own implementation, but please raise an issue (or +1 an issue) if you think the library should support a currently-unsupported format.

Upgrading from v0.x -> v1.x (Breaking Changes)

  1. twitter option removed, replaced with mention (which accepts 'twitter', 'instagram' and 'soundcloud' values)
  2. Matching mentions (previously the twitter option) now defaults to being turned off. Previously, Twitter handle matching was on by default.
  3. replaceFn option now called with just one argument: the Match object (previously was called with two arguments: autolinker and match)
  4. (Used inside the replaceFn) TwitterMatch replaced with MentionMatch, and MentionMatch.getType() now returns 'mention' instead of 'twitter'
  5. (Used inside the replaceFn) TwitterMatch.getTwitterHandle() -> MentionMatch.getMention()

Developing / Contributing

Pull requests definitely welcome. To setup the project, make sure you have Node.js installed. Then open up a command prompt and type the following:

npm install -g pnpm@latest   # this project uses pnpm workspaces, and pnpm is a faster npm anyway :)

cd Autolinker.js             # where you cloned the project
pnpm install

To run the tests:

pnpm run test
  • Make sure to add tests to check your new functionality/bugfix
  • Run the pnpm run test command to test

Running the Live Example Page Locally

Run:

pnpm run devserver

Then open your browser to: http://localhost:8080/docs/examples/index.html

You should be able to make a change to source files, and refresh the page to see the changes.

Running the benchmarks

Run:

pnpm run benchmarks

Note: See the Benchmarks Table above for current results.

Couple points on the benchmarks:

  • These benchmarks attempt to set up all libraries by configuring comparable features to Autolinker (e.g.: linking emails, hashtags, mentions, etc.) to try to get an apples-to-apples comparison.
  • While developing, recommend running the benchmarks a few times both before and after making any changes if developing.
  • See the benchmarks folder and benchmarks/input-text.ts for how the benchmarks are set up and what input they are given.

Documentation Generator Notes

This project uses JSDuck for its documentation generation, which produces the page at http://gregjacobs.github.io/Autolinker.js.

Unfortunately, JSDuck is a very old project that is no longer maintained. As such, it doesn't support TypeScript or anything from ES6 (the class keyword, arrow functions, etc). However, I have yet to find a better documentation generator that creates such a useful API site. (Suggestions for a new one are welcome though - please raise an issue.)

Since ES6 is not supported, we must generate the documentation from the ES5 output. As such, a few precautions must be taken care of to make sure the documentation comes out right:

  1. @cfg documentation tags must exist above a class property that has a default value, or else it won't end up in the ES5 output. For example:

    // Will correctly end up in the ES5 output

/**
 * @cfg {String} title
 */
readonly title: string = '';



// Will *not* end up in ES5 output, and thus, won't end up in the generated
// documentation

/**
 * @cfg {String} title
 */
readonly title: string;

  2. The @constructor tag must be replaced with @method constructor

To build the documentation, you will need Ruby installed (note: Ruby comes pre-installed on MacOS), with the JSDuck gem.

See https://github.com/senchalabs/jsduck#getting-it for installation instructions on Windows/Mac/Linux.

Changelog

See Releases

npm-compare.com is an independent website designed to help developers choose the most suitable npm packages. We are not affiliated with npm, Inc, the official website for the npm registry. Note that npm is a registered trademark of npm, Inc. For more details, please refer to our Terms & Privacy.