README.md

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.

A build repository is maintained here.

Jump to

• Features
• Demo
• Installation and Usage
  • Quick Start
  • Node.js/Browserify
  • AMD Modules
  • Browser
• Browser Support
• Node.js Support
• Downloads
• API Documentation
• 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 analyzed 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.
  • Linkify is compatible with all modern browsers, as well as Internet Explorer 9 and up.

Demo

Launch demo

Installation and Usage

View full documentation.

Download the latest release, or install via NPM

npm install --no-optional linkifyjs

or Yarn

yarn add --ignore-optional linkifyjs

or Bower

bower install linkifyjs

Quick Start

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

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

Note: A polyfill is required for Internet Explorer 8.

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/Browserify

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

Example string usage

linkifyHtml('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'), {
    className: '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="react.js"></script>
<script src="react-dom.js"></script>
<script src="linkify.js"></script>
<script src="linkify-react.js"></script>

linkify.test('dev@example.com'); // true

ReactDOM.render(
  <Linkify options={{ignoreTags: ['style']}}>
    Check out soapboxhq.com it is great!
  </Linkify>,
  document.getElementById('#container');
);

Browser Support

Linkify works on all modern browsers.

Linkify natively supports Internet Explorer 9 and above. Internet Explorer 8 is unofficially supported with a polyfill.

You can use either es5-shim (sham also required) or the provided linkify-polyfill.js:

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

<!--[if IE 8]>
<script src="linkify-polyfill.js"></script>
<![endif]-->
<script src="linkify.js"></script>
<script src="linkify-jquery.js"></script>

Node.js Support

Linkify is tested on Node.js 8 and up. Older versions are unofficially supported.

Downloads

Download the latest release or clone the build repository.

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)

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

API Documentation

View full documentation at soapbox.github.io/linkifyjs/docs/.

Caveats

The core linkify library (excluding plugins) attempts to find emails and URLs that match RFC specifications. However, it doesn't always get it right.

Here are a few of the known issues.

• Non-standard email local parts delimited by " (quote characters)
  • Emails with quotes in the localpart are detected correctly, unless the quotes contain certain characters like @.
• Slash characters in email addresses
• Non-latin domains or TLDs are not supported (support may be added via plugin in the future)

Contributing

Check out CONTRIBUTING.md.

License

MIT

Authors

Linkify is built with Love™ and maintained by SoapBox Innovations.