Linkify

Linkify is a small yet comprehensive JavaScript plugin for finding URLs in plain-text and converting them to HTML links. It works with all valid URLs and email addresses.

Jump to

• Features
• Demo
• Installation and Usage
  • Quick Start
  • Usage
    • Node.js/Browserify
    • AMD Modules
    • Browser
• API
• Plugin API
• Caveats
• Contributing
• License

Features

• Accuracy
  Linkify uses a (close to) complete list of valid top-level domains to ensure that only valid URLs and email addresses are matched.
• Speed
  Each string is analyzied exactly once to detect every kind of linkable entity
• Extensibility
  Linkify is designed to be fast and lightweight, but comes with a powerful plugin API that lets you detect even more information like #hashtags and @mentions.
• Small footprint
  Linkify and its jQuery interface clock in at approximately 15KB minified (5KB gzipped) - approximately 50% the size of Twitter Text
• Modern implementation
  Linkify is written in ECMAScript6 and compiles to ES5 for modern JavaScript runtimes.

Demo

Launch demo

Installation and Usage

Quick Start

Add linkify and linkify-jquery to your HTML following jQuery:

<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.2/jquery.min.js"></script>
<script src="linkify.min.js"></script>
<script src="linkify-jquery.min.js"></script>

Find all links and convert them to anchor tags

$('p').linkify();
$('#sidebar').linkify({
    target: "_blank"
});

Find all links in the given string

linkify.find('Any links to github.com here? If not, contact test@example.com');

Returns the following array

[
  {
    type: 'url',
    value: 'github.com',
    href: 'http://github.com'
  },
  {
    type: 'email',
    value: 'test@example.com',
    href: 'mailto:test@example.com'
  }
]

See all available options

Node.js/io.js/Browserify

var linkify = require('linkifyjs');
var linkifyStr = require('linkifyjs/string');
require('linkifyjs/plugin/hashtag')(linkify); // optional

Example string usage

linkifyStr('The site github.com is #awesome.', {
  defaultProtocol: 'https'
});

Returns the following string

'The site <a href="https://github.com">github.com</a> is <a href="#awesome">#awesome</a>.'

AMD

<script src="r.js"></script>
<script src="linkify.amd.js"></script>
<script src="linkify-plugin-hashtag.amd.js"></script> <!-- optional -->
<script src="linkify-element.amd.js"></script>

require(['linkify'], function (linkify) {
  linkify.test('github.com'); // true
  linkify.test('github.com', 'email'); // false
});

require(['linkify-element'], function (linkifyElement) {

  // Linkify the #sidebar element
  linkifyElement(document.getElementById('#sidebar'), {
    linkClass: 'my-link'
  });

  // Linkify all paragraph tags
  document.getElementsByTagName('p').map(linkifyElement);

});

Note that if you are using linkify-jquery.amd.js, a jquery module must be defined.

Browser globals

<script src="jquery.js"></script>
<script src="linkify.js"></script>
<script src="linkify-string.js"></script>
<script src="linkify-jquery.js"></script>

linkify.test('dev@example.com'); // true
var htmlStr = linkifyStr('Check out soapboxhq.com it is great!');
$('p').linkify();

Downloads

linkify (required)
.min.js · .js · .amd.min.js · .amd.js

Interfaces (recommended - include at least one)

• string
  .min.js · .js · .amd.min.js · .amd.js
• jquery
  .min.js · .js · .amd.min.js · .amd.js
• element (Included with linkify-jquery)
  .min.js · .js · .amd.min.js · .amd.js

Plugins (optional)

• hashtag
  .min.js · .js · .amd.min.js · .amd.js

API

Jump To

• Standard
• string
• jquery
  • DOM Data API
• element
• Options
• Plugins

Standard linkify

Installation

Node.js/io.js/Browserify

var linkify = require('linkifyjs');

AMD

<script src="linkify.amd.js"></script>
<script>
    require(['linkify'], function (linkify) {
        // ...
    });
</script>

Browser globals

<script src="linkify.js"></script>

Methods

linkify.find (str)

Finds all links in the given string

Params

• String str Search string

Returns Array List of links where each element is a hash with properties type, value, and href

linkify.find('For help with GitHub.com, please email support@github.com');

Returns the array

[{
    type: 'url',
    value: 'GitHub.com',
    href: 'http://github.com',
}, {
    type: 'email',
    value: 'support@github.com',
    href: 'mailto:support@github.com'
}]

linkify.test (str)

Is the given string a link? Not to be used for strict validation - See Caveats

Params

• String str Test string

Returns Boolean

linkify.test('google.com'); // true
linkify.test('google.com', 'email'); // false

linkify.tokenize (str)

Internal method used to perform lexicographical analysis on the given string and output the resulting token array.

Params

• String str

Returns Array

linkify-jquery

Provides the Linkify jQuery plugin.

Installation

Node.js/io.js/Browserify

var $ = require('jquery');
require('linkifyjs/jquery')($);

AMD

Note that linkify-jquery requires a jquery module.

<script src="jquery.amd.js"></script>
<script src="linkify.amd.js"></script>
<script src="linkify-jquery.amd.js"></script>

require(['jquery'], function ($) {
  // ...
});

Browser globals

<script src="jquery.js"></script>
<script src="linkify.js"></script>
<script src="linkify-jquery.js"></script>

Usage

var options = { /* ... */ };
$(selector).linkify(options);

Params

• Object [options] Options hash

See all available options.

DOM Data API

The jQuery plugin also provides a DOM data/HTML API - no extra JavaScript required!

<!-- Find and linkify all entities in this div -->
<div data-linkify="this">...</div>

<!-- Find and linkify the paragraphs and `#footer` element in the body -->
<body data-linkify="p, #footer">...</body>

Additional data options are available.

linkify-string

Interface for replacing links within native strings with anchor tags. Note that this function will not parse HTML strings properly - use linkify-element or linkify-jquery instead.

Installation

Node.js/io.js/Browserify

var linkifyStr = require('linkifyjs/string');

AMD

<script src="linkify.amd.js"></script>
<script src="linkify-string.amd.js"></script>
<script>
    require(['linkify-string'], function (linkifyStr) {
        // ...
    });
</script>

Browser globals

<script src="linkify.js"></script>
<script src="linkify-string.js"></script>

Usage

var options = {/* ... */};
var str = 'For help with GitHub.com, please email support@github.com';
linkifyStr(str, options);
// or
str.linkify(options);

Returns

'For help with <a href="http://github.com" target="_blank">GitHub.com</a>, please email <a href="mailto:support@github.com">support@github.com</a>'

Params

• String str String to linkify
• Object [options] Options hash

Returns String Linkified string

Plugins

Plugins provide no new interfaces but add additional detection functionality to Linkify. A custom plugin API is currently in the works.

hashtag

Adds basic support for Twitter-style hashtags.

// Node.js/Browserify
var linkify = require('linkifyjs');
require('linkifyjs/plugins/hashtag')(linkify);

<!-- Global `linkifyStr` -->
<script src="linkify.js"></script>
<script src="linkify-plugin-hashtag.js"></script>

<!-- AMD -->
<script src="linkify.amd.js"></script>
<script src="linkify-plugin-hashtag.amd.js"></script>
<script>
    require(['linkify'], function (linkify) {
        // ...
    });
</script>

Usage

var options = {/* ... */};
var str = "Linkify is #super #rad";

linkify.find(str);
/* [
 {type: 'hashtag', value: "#super", href: "#super"},
 {type: 'hashtag', value: "#rad", href: "#rad"}
] */

// If the linkifyStr interface has also been included
linkifyStr(str)

Options

Linkify is applied with the following default options. Below is a description of each.

var options = {
  tagName: 'span',
  defaultProtocol: 'https',
  target: '_parent',
  nl2br: true,
  linkClass: 'a-new-link',
  linkAttributes: {
    rel: 'nofollow'
  },
  format: function (link, type) {
    if (type === 'hashtag') {
      link = link.toLowerCase();
    }
    return link;
  },
  formatHref: function (link, type) {
    if (type === 'hashtag') {
      link = 'https://twitter.com/hashtag/' + link.replace('#', '');
    }
    return link;
  }
};

// jQuery
$('selector').linkify(options);

// String
linkifyStr(str, options);
str.linkify(options);

Plugin API

Coming soon

Caveats

Contributing

Authors

Linkify is handcrafted with Love by SoapBox Innovations, Inc.