What is autolinker?
Autolinker is a utility for automatically linking URLs, email addresses, phone numbers, and social media handles in plain text. It transforms these elements into clickable links, making it easier to navigate and interact with text content.
What are autolinker's main functionalities?
Link URLs
Automatically converts URLs in the text into clickable links.
const Autolinker = require('autolinker');
const linkedText = Autolinker.link('Check out this website: www.example.com');
console.log(linkedText); // 'Check out this website: <a href="http://www.example.com" target="_blank">www.example.com</a>'
Link Email Addresses
Automatically converts email addresses in the text into clickable mailto links.
const Autolinker = require('autolinker');
const linkedText = Autolinker.link('Contact us at info@example.com');
console.log(linkedText); // 'Contact us at <a href="mailto:info@example.com">info@example.com</a>'
Link Phone Numbers
Automatically converts phone numbers in the text into clickable tel links.
const Autolinker = require('autolinker');
const linkedText = Autolinker.link('Call us at 123-456-7890');
console.log(linkedText); // 'Call us at <a href="tel:123-456-7890">123-456-7890</a>'
Link Social Media Handles
Automatically converts social media handles in the text into clickable links to the respective social media profiles.
const Autolinker = require('autolinker');
const linkedText = Autolinker.link('Follow us on Twitter @example');
console.log(linkedText); // 'Follow us on Twitter <a href="https://twitter.com/example" target="_blank">@example</a>'
Other packages similar to autolinker
linkifyjs
LinkifyJS is a versatile library for finding and converting URLs, email addresses, and hashtags in plain text into clickable links. It offers more customization options compared to Autolinker, such as custom link types and formats.
anchor-js
AnchorJS is a lightweight library that adds anchor links to headings in your HTML content. While it focuses on a different use case than Autolinker, it provides a simple way to enhance navigation within a document.
linkify-it
Linkify-it is a fast and lightweight library for finding and converting URLs in plain text into clickable links. It is highly customizable and can be extended with plugins to support additional link types.
Autolinker.js

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:
Autolinker@4.1.5 | 3,278 | ±0.40% | Fastest ✅ |
anchorme@3.0.8 | 2,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.0 | 491 | ±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');
Browser
<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");
const linkedText = Autolinker.link("Check out google.com", {
newWindow: false
});
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 <
and
>
, 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
});
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
});
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");
autolinker.link( "Go to www.google.com" );
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 = "...";
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;
case 'email':
const email = match.getEmail();
console.log("email: ", email);
if(email === "my@own.address") {
return false;
} else {
return;
}
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 = "...";
const linkedText = Autolinker.link( input, {
replaceFn : function( match ) {
console.log("href = ", match.getAnchorHref());
console.log("text = ", match.getAnchorText());
const tag = match.buildTag();
tag.setAttr('rel', 'nofollow');
tag.addClass('external-link');
tag.setInnerHtml('Click here!');
return tag;
}
} );
The replaceFn
is provided one argument:
A replacement of the match is made based on the return value of the function.
The following return values may be provided:
- No return value (
undefined
), or true
(boolean): Delegate back to
Autolinker to replace the match as it normally would.
false
(boolean): Do not replace the current match at all - leave as-is.
- Any string: If a string is returned from the function, the string will be used
directly as the replacement HTML for the match.
- 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)
- Internet Explorer support has been removed since its official demise in June
2022.
- 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').
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
.
- 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.
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)
- If you are still on v1.x, first follow the instructions in the
Upgrading from v1.x -> v2.x
section below.
- 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)
-
If you are still on v0.x, first follow the instructions in the
Upgrading from v0.x -> v1.x
section below.
-
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
:
import Autolinker, { Match } from 'autolinker';
The require()
interface is still supported as well for Node.js:
const Autolinker = require('autolinker');
-
You will no longer need the @types/autolinker
package as this package now
exports its own types
-
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)
twitter
option removed, replaced with mention
(which accepts 'twitter',
'instagram' and 'soundcloud' values)
- Matching mentions (previously the
twitter
option) now defaults to
being turned off. Previously, Twitter handle matching was on by
default.
replaceFn
option now called with just one argument: the Match
object (previously was called with two arguments: autolinker
and
match
)
- (Used inside the
replaceFn
) TwitterMatch
replaced with
MentionMatch
, and MentionMatch.getType()
now returns 'mention'
instead of 'twitter'
- (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
cd Autolinker.js
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:
-
@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:
readonly title: string = '';
readonly title: string;
-
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