Autolinker.js

Because I had so much trouble finding a good autolinking 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 Twitter handles.
• 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

Using with Node.js via npm:

Command Line:

npm install autolinker --save

JavaScript:

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

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 );

Example:

var linkedText = Autolinker.link( "Check out google.com", { className: "myLink" } );
// Produces: "Check out <a class="myLink myLink-url" href="http://google.com" target="_blank">google.com</a>"

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
  A number for how many characters long URLs/emails/twitter handles should be truncated to inside the text of a link. If the URL/email/twitter 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..'

• 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"/"twitter" suffixes for styling url/email/twitter links differently.

  For example, if this config is provided as "myLink", then:

  1. URL links will have the CSS classes: "myLink myLink-url"
     
  2. Email links will have the CSS classes: "myLink myLink-email", and
     
  3. Twitter links will have the CSS classes: "myLink myLink-twitter"
     

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

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

• twitter : Boolean
  true to have Twitter handles auto-linked, false to skip auto-linking of Twitter handles. Defaults to true.

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 } );
// 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:

var 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:

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" );
// 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>"

Changelog:

0.9.0

• Added better support for the processing of existing HTML in the input string. Now handles namespaced tags, and attribute names with dashes or any other Unicode character (thanks @aziraphale)

0.8.0

• Added className option for easily styling produced links (thanks @busticated)
• Refactored into a JS class. Autolinker can now be instantiated using:

var 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>"

This allows options to be set on a single instance, and used throughout a codebase by injecting the autolinker instance as a dependency to the modules/classes that use it. (Note: Autolinker may still be used with the static Autolinker.link() method as was previously available as well.)

0.7.0

• Changed build system to Grunt.
• Added AMD and CommonJS module loading support (ex: RequireJS, and Node.js's module loader).
• Added command line Jasmine test runner (grunt test)
• Upgraded Jasmine from 1.3.1 to 2.0
• Added license header to dist files.

(Thanks to @busticated!)

0.6.1

• Added LICENSE file to repository.

0.6.0

• Added options for granular control of which types are linked (urls, email addresses, and/or twitter handles). (thanks @aziraphale)

0.5.0

• Simplified the path / query string / hash processing into a single regular expression instead of 3 separate ones.
• Added support for parenthesis in URLs, such as: en.wikipedia.org/wiki/IANA_(disambiguation) (thanks @dandv)
• Add all known top-level domains (TLDs) (thanks @wouter0100)

0.4.0

Merged pull requests from @afeld:

• strip protocol and 'www.' by default - fixes #1
• truncate URLs from the end
• make simpler regex for detecting prefix
• remove trailing slashes from URLs, and handle periods at the end of paths
• re-use domain+TLD regexes for email matching
• add .me and .io to list of TLDs

Thanks Aidan :)

0.3.1

• Fixed an issue with handling nested HTML tags within anchor tags.

0.3

• Implemented the truncate option.

0.2

• Implemented autolinking Twitter handles.

0.1

• Initial implementation, which autolinks URLs and email addresses. Working on linking Twitter handles.