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');
require('linkifyjs/plugin/hashtag')(linkify); // optional
var linkifyStr = require('linkifyjs/string');

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

Plugins (optional)

• hashtag
  .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

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 [, type])

Finds all links in the given string

Params

• String str Search string
• String [type] (Optional) only find links of the given type

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

• type is the type of entity found. Possible values are
  • 'url'
  • 'email'
  • 'hashtag' (with Hashtag plugin)
• value is the original entity substring.
• href should be the value of this link's href attribute.

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 [, type])

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

Params

• String str Test string
• String [type] (Optional) returns true only if the link is of the given type (see linkify.find),

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')($, document);

Where the second argument is your window.document implementation (not required for Browserify).

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.

Note: Plugins should be included before interfaces.

General Installation

Node.js/io.js/Browserify

var linkify = require('linkifyjs')
require('linkifyjs/plugin/<name>')(linkify);

AMD

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

Browser globals

<script src="linkify.js"></script>
<script src="linkify-plugin-<name>.js"></script>

hashtag Plugin

Adds basic support for Twitter-style hashtags.

var linkify = require('linkifyjs');
require('linkifyjs/plugins/hashtag')(linkify);

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

linkify.find(str);

Returns the following array

[
  {
    type: 'hashtag',
    value: "#super",
    href: "#super"
  },
  {
    type: 'hashtag',
    value: "#rad2015",
    href: "#rad2015"
  }
]

Options

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

var options = {
  defaultProtocol: 'http',
  format: null,
  formatHref: null,
  linkAttributes: null,
  linkClass: 'linkified',
  nl2br: false,
  tagName: 'a',
  target: function (type) {
    return type === 'url' ? '_blank' : null;
  }
};

Usage

linkifyStr(str, options); // or `str.linkify(options)`
linkifyElement(document.getElementById(id), options);
$(selector).linkify(options);

defaultProtocol

Type: String
Default: 'http'
Values: 'http', 'https', 'ftp', 'ftps', etc.
Data API: data-linkify-default-protocol

Protocol that should be used in href attributes for URLs without a protocol (e.g., github.com).

format

Type: Function (String value, String type)
Default: null

Format the text displayed by a linkified entity. e.g., truncate a long URL.

'http://github.com/SoapBox/linkifyjs/search/?q=this+is+a+really+long+query+string'.linkify({
  format: function (value, type) {
    if (type === 'url' && value.length > 50) {
      value = value.slice(0, 50) + '…';
    }
    return value;
  }
});

formatHref

nl2br

tagName

target

linkAttributes

linkClass

Plugin API

Coming soon

Caveats

Contributing

Authors

Linkify is handcrafted with Love by SoapBox Innovations, Inc.