This page is outdated

You are reading documentation for Linkify v2. Browse the latest v3+ documentation.

Jump To

Options

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

linkify.options.defaults = {
  attributes: null,
  className: 'linkified',
  defaultProtocol: 'http',
  events: null,
  format: function (value, type) {
    return value;
  },
  formatHref: function (href, type) {
    return href;
  },
  ignoreTags: [],
  nl2br: false,
  tagName: 'a',
  target: {
    url: '_blank'
  },
  validate: true
};

Note: The default .linkified class will be removed in a future release

These defaults are stored at linkify.options.defaults can be set globally from there.

Warning: Use default overrides sparingly. If you cannot guarantee that you are linkify's only consumer, don't override the defaults.

General Usage

linkifyStr(str, options); // or `str.linkify(options)`
linkifyHtml(str, options);
linkifyElement(document.getElementById('id'), options);
$(selector).linkify(options);
React.createElement(Linkify, {options: options}, str);

attributes

  • Type: Object | Function (String href, String type)
  • Default: null

Object of attributes to add to each new link. Note: the class and target attributes have dedicated options.

Also accepts a function that takes the unformatted href, the link type (e.g., 'url', 'email', etc.) and returns the object.

'github.com'.linkify({
  attributes: {
    rel: 'nofollow'
  }
});

className

  • Type: String | Function (String href, String type) | Object
  • Default: 'linkified' (may be removed in future releases)
  • Data API: data-linkify-class-name

class attribute to use for newly created links.

Accepts a function that takes the unformatted href value and link type (e.g., 'url', 'email', etc.) and returns the string.

Accepts an object where each key is the link type and each value is the string or function to use for that type.

Note: The default linkified class name is deprecated and will be removed in a future release.

'github.com'.linkify({
  className: 'new-link--url'
});

// or

'github.com'.linkify({
  className: function (href, type) {
    return 'new-link--' + type
  }
});

// or
'github.com'.linkify({
  className: {
    url: 'new-link--url',
    email: function (href) {
      return 'new-link--email';
    }
  }
});

Returns

<a href="http://github.com" class="new-link--url">github.com</a>

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

events

*element, jquery interfaces only*

  • Type: Object | Function (String href, String type) | Object
  • Default: null

Add event listeners to newly created link elements. Takes a hash where each key is an standard event name and the value is an event handler.

Also accepts a function that takes the unformatted href and the link type (e.g., 'url', 'email', etc.) and returns the hash.

$('p').linkify({
  events: {
    click: function (e) {
      alert('Link clicked!');
    },
    mouseover: function (e) {
      alert('Link hovered!');
    }
  }
});

For React, specify events in the attributes option as standard React events.

See the React Event docs and the linkify-react event docs

format

  • Type: Function (String value, String type) | Object
  • Default: null

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

Accepts an object where each key is the link type (e.g., 'url', 'email', etc.) and each value is the formatting function to use for that type.

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

// or

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

formatHref

  • Type: Function (String href, String type) | Object
  • Default: null

Similar to format, except the result of this function will be used as the href attribute of the new link.

This is useful when finding hashtags, where you don’t necessarily want the default to be a link to a named anchor.

Accepts an object where each key is the link type (e.g., 'url', 'email', etc.) and each value is the formatting function to use for that type.

'This site is #rad'.linkify({
  formatHref: function (href, type) {
    if (type === 'hashtag') {
      href = 'https://twitter.com/hashtag/' + href.substring(1);
    }
    return href;
  }
});

// or

'Hey @nfrasser, check out issue #23'.linkify({
  formatHref: {
    mention: function (href) {
      return 'https://github.com' + href;
    },
    ticket: function (href) {
      return 'https://github.com/Hypercontext/linkifyjs/issues/' + href.substring(1);
    }
  }
});

ignoreTags

*element, html, and jquery interfaces only*

  • Type: Array
  • Default: []

Prevent linkify from trying to parse links in the specified tags. This is useful when running linkify on arbitrary HTML.

linkifyHtml(
  'Please ignore <script>var a = {}; a.com = "Hi";</script> \n' +
  'but do <span>b.ca</span>', {
  ignoreTags: [
    'script',
    'style'
  ]
});

Returns

Please ignore <script>var a = {}; a.com = "Hi";</script>
but do <span><a href="http://b.ca" class="linkified" target="_blank">b.ca</a></span>

Notice that there is no hyperlink at “a.com” inside the script tag.

nl2br

  • Type: Boolean
  • Default: false
  • Data API: data-linkify-nl2br

If true, \n line breaks will automatically be converted to <br> tags.

tagName

  • Type: String | Function (String href, String type) | Object
  • Default: a
  • Data API: data-linkify-tagname

The tag name to use for each link. For cases where you can’t use anchor tags.

Accepts a function that takes the unformatted href, the link type (e.g., 'url', 'email', etc.) and returns the tag name.

Accepts an object where each key is the link type and each value is the tag name to use for that type.

'github.com'.linkify({
  tagName: 'span'
});

// or

'#swag'.linkify({
  tagName: {
    hashtag: 'span'
  }
});

Returns

<span href="http://github.com">github.com</span>

target

  • Type: String | Function (String href, String type) | Object
  • Default: '_blank' for URLs, null for everything else
  • Data API: data-linkify-target

target attribute for generated link.

Accepts a function that takes the unformatted href, the link type (e.g., 'url', 'email', etc.) and returns the target

Accepts an object where each key is the link type and each value is the target to use for that type.

'github.com'.linkify({
  target: '_parent'
});

// or
'test-email@example.com'.linkify({
  target: {
    url: '_parent',
    email: null
  }
});

validate

  • Type: Boolean | Function (String value, String type) | Object
  • Default: null

If option resolves to false, the given value will not show up as a link.

Accepts a function that takes a discovered link and the link type (e.g., 'url', 'email', etc.) and returns true if the link should be converted into an anchor tag, and false otherwise.

Accepts an object where each key is the link type and each value is the the validation option to use for that type

// Don't linkify links that don't begin in a protocol
// e.g., "http://google.com" will be linkified, but "google.com" will not.
'www.google.com'.linkify({
  validate: {
    url: function (value) {
      return /^(http|ftp)s?:\/\//.test(value);
    }
  }
});

linkClass

Deprecated. Use className instead.

linkAttributes

Deprecated. Use attributes instead.