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
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 out there
was either an implementation that didn't cover every case, 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 properly handle URLs with special characters
- Will properly handle URLs with query parameters or a named anchor (i.e. hash)
- Will autolink email addresses.
- Will autolink phone numbers.
- Will autolink Twitter handles.
- Will autolink hashtags.
- Will properly handle HTML input. The utility will not change the
href
attribute inside anchor (<a>) tags (or any other tag/attribute for that
matter), and will not accidentally wrap the inner text of an anchor tag with a
new one (which would cause doubly-nested anchor tags).
Hope that this utility helps you as well!
Installation
Download
Simply clone or download the zip of the project, and link to either
dist/Autolinker.js
or dist/Autolinker.min.js
with a script tag:
<script src="path/to/Autolinker.min.js"></script>
Using with the Bower package manager:
Command line:
bower install Autolinker.js --save
Command Line:
npm install autolinker --save
JavaScript:
var Autolinker = require( 'autolinker' );
Usage
Using the static link()
method:
var linkedText = Autolinker.link( textToAutolink[, options] );
Using as a class:
var autolinker = new Autolinker( [ options ] );
var linkedText = autolinker.link( textToAutoLink );
Note: if using the same options to autolink multiple pieces of html/text, it is
slightly more efficient to create a single Autolinker instance, and run the
link()
method repeatedly (i.e. use the "class" form above).
Example:
var linkedText = Autolinker.link( "Check out google.com", { className: "myLink" } );
Options
These 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
.
-
stripPrefix : Boolean
true
to have the 'http://' or 'https://' and/or the 'www.' stripped from the
beginning of links, false
otherwise. 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"/"twitter"/"hashtag"
suffixes for styling url/email/phone/twitter/hashtag links differently.
For example, if this config is provided as "myLink", then:
- URL links will have the CSS classes: "myLink myLink-url"
- Email links will have the CSS classes: "myLink myLink-email"
- Phone links will have the CSS classes: "myLink myLink-phone"
- Twitter links will have the CSS classes: "myLink myLink-twitter"
- Hashtag links will have the CSS classes: "myLink myLink-hashtag"
-
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. - wwwMatches (Boolean):
true
to match urls found prefixed with 'www.'
,
i.e. www.google.com
. false
to prevent these types of matches. Note
that if the URL had a prefixed scheme, and schemeMatches
is true, it
will still be linked. - tldMatches:
true
to match URLs with known top level domains (.com, .net,
etc.) that are not prefixed with a scheme or 'www.'
. Ex: google.com
,
asdf.org/?page=1
, etc. false
to prevent these types of matches.
Example usage: urls: { schemeMatches: true, wwwMatches: true, tldMatches: false }
-
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
.
-
twitter : Boolean
true
to have Twitter handles auto-linked, false
to skip auto-linking of
Twitter handles. Defaults to true
.
-
hashtag : Boolean/String
A string for the service name to have hashtags auto-linked to. Supported
values at this time are 'twitter', 'facebook' and 'instagram'. Pass false
to skip
auto-linking of hashtags. Defaults to false
.
-
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.
For example, if you wanted to disable links from opening in new windows, you could do:
var 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:
var 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:
var 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):
var 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" );
Custom Replacement Function
A custom replacement function (replaceFn)
may be provided to replace url/email/phone/Twitter handle/hashtag matches on an
individual basis, based on the return from this function.
Full example, for purposes of documenting the API:
var input = "...";
var linkedText = Autolinker.link( input, {
replaceFn : function( autolinker, match ) {
console.log( "href = ", match.getAnchorHref() );
console.log( "text = ", match.getAnchorText() );
switch( match.getType() ) {
case 'url' :
console.log( "url: ", match.getUrl() );
if( match.getUrl().indexOf( 'mysite.com' ) === -1 ) {
var tag = match.buildTag();
tag.setAttr( 'rel', 'nofollow' );
tag.addClass( 'external-link' );
return tag;
} else {
return true;
}
case 'email' :
var email = match.getEmail();
console.log( "email: ", email );
if( email === "my@own.address" ) {
return false;
} else {
return;
}
case 'phone' :
var phoneNumber = match.getNumber();
console.log( phoneNumber );
return '<a href="http://newplace.to.link.phone.numbers.to/">' + phoneNumber + '</a>';
case 'twitter' :
var twitterHandle = match.getTwitterHandle();
console.log( twitterHandle );
return '<a href="http://newplace.to.link.twitter.handles.to/">' + twitterHandle + '</a>';
case 'hashtag' :
var hashtag = match.getHashtag();
console.log( hashtag );
return '<a href="http://newplace.to.link.hashtag.handles.to/">' + hashtag + '</a>';
}
}
} );
The function is provided two arguments:
- The Autolinker instance that is performing replacements. This can be used to
query the options that the Autolinker instance is configured with, or to
retrieve its TagBuilder instance (via autolinker.getTagBuilder()).
- 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:
- 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/docs/
Contributing
Pull requests definitely welcome.
- Make sure to add tests to cover your new functionality/bugfix.
- Run the
gulp
command to build/test (or alternatively, open the tests/index.html
file to run the tests). - When committing, please omit checking in the files in the
dist/
folder after building/testing. These are only committed to the repository for users downloading Autolinker via Bower. I will build these files and assign them a version number when merging your PR. - Please use tabs for indents! Tabs are better for everybody (individuals can set their editors to different tab sizes based on their visual preferences).
Changelog
See Releases