Overview

Javascript library to detect links / URLs / Emails in text and convert them to clickable HTML anchor links. You can also use it for extracting a list of valid links and emails out of text or use it as a validation library for emails, URLs and IPs.

Features

  • Sensitivity: It’s Highly sensitive with the least false positives.
    • It validates URLs and Emails against full IANA list.
    • Validates port numbers (if present).
    • Validates IP octet numbers (if present).
  • Robustness:
    • Skips HTML, so it doesn’t break your HTML if it had a URL as an attribute for an element.
    • Links with or without protocols.
    • Works with IPs, FTPs, Emails and files.
    • Can detect parenthesis and quotation marks as part of the URL or as a surrounding to the URL.
  • Fast: It’s definitely fast! processing the full H.G. Wells "The Time Machine" novel (633 KB text file) with over 1500 URLs inserted at random places takes about 3 seconds.
  • Light Weight: Although it’s a feature rich library with a full IANA list included, it’s only 6KB when minified and gzipped.

Demo

Input:

Output:

Installation

You can get this library via NPM

npm i --save anchorme

Or download the single filed compiled version here.

Usage

Basic usage

The anchorme library exports one function that can receives one or two parameters:

anchorme(input:string,[options:object])

The example below demonstrates basic usage with no options


var anchorme = require("anchorme").default; // if installed via NPM
import anchorme from "anchorme"; // ES6 / Typescript style imports
var someText = "this is a text with a link www.github.com ..";
var result = anchorme(someText);
// You can also pass few options (totally optional)
// to add attribute, truncate results, setting default protocols and more
// read below
					

Truncation

Key Value type Default value
truncate
Number|[Number,Number]
Infinity

This will convert a long link like this: https://raw.githubusercontent.com/alexcorvi/anchorme.js/gh-pages/src/tests/hasprotocol.js to this: https://raw.githubusercontent.com/alexcorv...

However, if you wanted to remove characters from the middle instead of the end to produce a link like this: raw.githubusercontent.com/.../hasprotocol.js; you can pass an array of two numbers first number is the number of desired characters at the beginning and second number is the number of desired characters at the end.

Example:


anchorme(string,{
	truncate:40 // 40 is the maximum length of the viewed link
});
anchorme(string,{
	truncate:[26,15],
	// means 26 characters from the beginning
	// and 15 characters from the end
});
					

JSFiddle Demo


Adding attributes

Key Value type Default value
attributes
Array<Object|Function>
[]

You can add attributes to the links produced by anchorme. using the `attributes` key in the options object. The value of this option should be an array of the attributes you'd like to pass.

Each value of this array can be either an object describing the attribute or a function that returns an object that describes the attribute


anchorme(string,{
	attributes:[ // attributes is an array
		// an object that describes the attribute
		// will produce: class="link"
		{
			name:"class",
			value:"link"
		},
		// a function that returns an object
		function(urlObj){
			if(urlObj.reason === "ip") return {name:"class",value:"ip-link"};
		},
		function(urlObj){
			if(urlObj.protocol !== "mailto:") return {name:"target",value:"blank"};
			// following conditions can also be used:
			// if(urlObj.raw.indexOf("@") > 0) return {name:"target",value:"blank"};
			// if(urlObj.reason !== "email") return {name:"target",value:"blank"};
		}
	]
});

Where urlObj is an object containing detailed info about the link in question. The example above will add `ip-link` class to all the links that are IPs, and add `target='_blank'` to all the links that are not emails.

If you log the urlObj you'll get something similar to this:


{
	// the reason this fragment
	// was detected
	// possible reasons: "file", "url", "ip", "email"
    reason: "email",
    // the protocol that the link came with
    // or the protocol that was added to the link
    protocol: "mailto:",
    // the link (without any modification)
    raw: "a@b.co",
    // the encoded version of the link
    // i.e. non-Latin characters -> URI encoding
    // also doesn't have a protocol (if it came with any)
    encoded: "a@b.co",
}
					

JSFiddle Demo


Default protocol

Key Value type Default value
defaultProtocol
String|Function
"http://"

If the link came without protocol, like www.google.com then anchorme will add the http:// by default. However you can set your own default protocol.


anchorme(string,{
	defaultProtocol:"ftp://",
	// ... or anything
});
					

In some cases, you might want the protocol to be set conditionally. Anchorme allows you to pass a function as the `defaultProtocol` and uses whatever this function returns.


anchorme(string,{
	defaultProtocol:function(url){
		// where url is like: "www.google.com"
		if(url.indexOf("google") > 0) return "https://";
		else return "http://";
	},
});
					

Please note that the default protocol does not apply on detected emails. Detected emails will always have mailto: as their protocol.

JSFiddle Demo


Excluding

Key Value type Default value
emails
Boolean
true
urls
Boolean
true
ips
Boolean
true
files
Boolean
true

You can exclude IPs/Emails/URLs/Files like this:


anchorme(string,{
	emails:false,
	urls:false,
	ips:false,
	files:false
})
// the example above won't do anything to your string
// since you're excluding every possible link that can be detected
					

JSFiddle Demo

Additional Features

Validation

anchorme.validate.ip(input:String)

anchorme.validate.email(input:String)

anchorme.validate.url(input:String)

You can use anchorme to validate emails, URLs and IPs.

Example:


anchorme.validate.ip("1.1.1.1:3000/something");
// returns true
anchorme.validate.ip("1.1.1.500:3000/something");
// returns false
anchorme.validate.email("alex@array.com");
// returns true
anchorme.validate.url("google.co.uk");
// returns true
					

JSFiddle Demo:


Listing

Although anchorme was authored to transform URLs in text strings to a click-able HTML anchor tags, passing `true` to `list` property in options will change the library's behavior and instead of returning a text with an HTML tags it will only return an array of valid URLs.


anchorme(myText,{
	list:true
});
// returns an array of detected valid URLs
					

JSFiddle Demo: