Versatile Keyword Highlighting Plugin For jQuery - mark.js

File Size: 218 KB
Views Total: 6747
Last Update:
Publish Date:
Official Website: Go to website
License: MIT
   
Versatile Keyword Highlighting Plugin For jQuery - mark.js

mark.js is a jQuery plugin that allows to highlight/mark searched text within a specific container. Supports regular expressions, diacritics, synonyms, custom class names, separate word search (multiple terms), filter selectors, word boundary and iframe element.

The Vanilla JavaScript Version is now available.

More examples:

Installation:

# NPM
$ npm install mark.js

# Bower
$ bower install mark.js

Basic usage:

1. Embed the latest version of jQuery library and mark.js script into your html document.

<script src="//code.jquery.com/jquery-1.12.2.min.js"></script>
<script src="dist/jquery.mark.min.js"></script>

2. Mark and highlight keyword searched by your users.

$("#selector").mark(keyword, options);

3. Available options for the mark() method.

// HTML element to wrap matches, e.g. span
element: "mark",  

// A class name that will be appended to element
className: "",   

// An array with exclusion selectors. 
// Elements matching those selectors will be ignored. 
// Example: "exclude": [".ignore", "*[data-ignore]"]
exclude: [],

// Whether to search for each word separated by a blank instead of the complete term
separateWordSearch: true,

// Either one of the following string values:
// "partially": When searching for "lor" only "lor" inside "lorem" will be marked
// "complementary": When searching for "lor" the whole word "lorem" will be marked
// "exactly": When searching for "lor" only those exact words with a word boundary will be marked. In this example nothing inside "lorem". This value is equivalent to the previous option wordBoundary
// Or an object containing two properties:
// "value": One of the above named string values
// "limiters": A custom array of string limiters for accuracy "exactly" or "complementary". 
accuracy: "partially",

// If diacritic characters should be matched. For example "piękny" would also match "piekny" and "doner" would also match "döner"
diacritics: true,

// An object with synonyms. The key will be a synonym for the value and the value for the key. 
// Example: "synonyms": {"one": "1"} will add the synonym "1" for "one" and vice versa
synonyms: {},

// Whether to search also inside iframes. 
// If you don't have permissions to some iframes (e.g. because they have a different origin) they will be silently skipped. 
// If you don't want to search inside specific iframes (e.g. facebook share), you can pass a filter selector that matches these iframes.
iframes: false,  

// The maximum ms to wait for a load event before skipping an iframe. 
// Especially important when there's no internet connection or a browser "offline" mode is enabled and an iframe has an online src – then the load event is never fired
iframesTimeout: 5000,

// Whether to search for matches across elements
"acrossElements": false,

// Whether to search case sensitive
"caseSensitive": false,

//  Whether to also find matches that contain soft hyphen, zero width space, zero width non-joiner and zero width joiner. They're used to indicate a point for a line break where there isn't enough space to show the full word.
"ignoreJoiners": false,

// An array of punctuation mark strings. These punctuation marks can be between any characters, e.g. setting this option to ["'"] would match "Worlds", "World's" and "Wo'rlds". 
// One or more apostrophes between the letters would still produce a match (e.g. "W'o''r'l'd's"). A typical setting for this option could be as follows: ":;.,-–—‒_(){}[]!'\"+=".split("")
ignorePunctuation: [],

// "disabled": Disable wildcard usage
// "enabled": When searching for "lor?m", the "?" will match zero or one non-space character (e.g. "lorm", "loram", "lor3m", etc). When searching for "lor*m", the "*" will match zero or more non-space characters (e.g. "lorm", "loram", "lor123m", etc).
// "withSpaces": When searching for "lor?m", the "?" will match zero or one space or non-space character (e.g. "lor m", "loram", etc). When searching for "lor*m", the "*" will match zero or more space or non-space characters (e.g. "lorm", "lore et dolor ipsum", "lor: m", etc).
wildcards: "disabled",

// A callback for each marked element. 
// This function receives the marked jQuery element as a parameter
each: function(){},   

// A callback function that will be called when there are no matches. Receives the not found term as a parameter
noMatch: function(){},

// A callback to filter or limit matches. It will receive the following parameters:
// The text node which includes the match
// The term that has been found
// A counter indicating the number of marks for the term
// A counter indicating the number of all marks
// The function must return false if the mark should be stopped, otherwise true
"filter": function(){},

// As jquery.mark is asynchronous this callback function is called after all marks are completed
done: function(){},   

// Set this option to true if you want to log messages
debug: false,

// Log messages to a specific object (only if debug is true)
log: console

4. Mark and highlight marched keyword using RegExp.

$("#selector").markRegExp(regexp, options);

5. Available options for the markRegExp method.

// HTML element to wrap matches, e.g. span
element: "mark",  

// A class name that will be appended to element
className: "",   

// An array with exclusion selectors. 
// Elements matching those selectors will be ignored. 
// Example: "exclude": [".ignore", "*[data-ignore]"]
exclude: [],

// Whether to search for each word separated by a blank instead of the complete term
separateWordSearch: true,

// Whether to search also inside iframes. 
// If you don't have permissions to some iframes (e.g. because they have a different origin) they will be silently skipped. 
// If you don't want to search inside specific iframes (e.g. facebook share), you can pass a filter selector that matches these iframes.
iframes: false,  

// The maximum ms to wait for a load event before skipping an iframe. 
// Especially important when there's no internet connection or a browser "offline" mode is enabled and an iframe has an online src – then the load event is never fired
iframesTimeout: 5000,

// Whether to search for matches across elements
"acrossElements": false,

// Indicates the number of matching groups to ignore in the replacement. 
// Can be used e.g. to implement non-capturing lookbehind groups. 
// Note that when the value is > 0 (when groups should be ignored), it expects a total amount of groups in the RegExp of ignoreGroups + 1
ignoreGroups: 0,

// A callback for each marked element. 
// This function receives the marked jQuery element as a parameter
each: function(){},   

// A callback function that will be called when there are no matches. Receives the not found term as a parameter
noMatch: function(){},

// A callback to filter or limit matches. It will receive the following parameters:
// The text node which includes the match
// The term that has been found
// A counter indicating the number of marks for the term
// A counter indicating the number of all marks
// The function must return false if the mark should be stopped, otherwise true
"filter": function(){},

// As jquery.mark is asynchronous this callback function is called after all marks are completed
done: function(){},   

// Set this option to true if you want to log messages
debug: false,

// Log messages to a specific object (only if debug is true)
log: console

6. Mark ranges using the markRanges() method.

$("#selector").markRegExp(ranges, {
  // defaults

  // HTML element to wrap matches, e.g. span
  element: "mark",  

  // A class name that will be appended to element
  className: "",   

  // An array with exclusion selectors. 
  // Elements matching those selectors will be ignored. 
  // Example: "exclude": [".ignore", "*[data-ignore]"]
  exclude: [],

  // Whether to search also inside iframes. 
  // If you don't have permissions to some iframes (e.g. because they have a different origin) they will be silently skipped. 
  // If you don't want to search inside specific iframes (e.g. facebook share), you can pass a filter selector that matches these iframes.
  iframes: false,  

  // The maximum ms to wait for a load event before skipping an iframe. 
  // Especially important when there's no internet connection or a browser "offline" mode is enabled and an iframe has an online src – then the load event is never fired
  iframesTimeout: 5000,

  // A callback for each marked element. 
  // This function receives the marked jQuery element as a parameter
  each: function(){},   

  // A callback function that will be called when there are no matches. Receives the not found term as a parameter
  noMatch: function(){},

  // A callback to filter or limit matches. It will receive the following parameters:
  // The text node which includes the match
  // The term that has been found
  // A counter indicating the number of marks for the term
  // A counter indicating the number of all marks
  // The function must return false if the mark should be stopped, otherwise true
  "filter": function(){},

  // As jquery.mark is asynchronous this callback function is called after all marks are completed
  done: function(){},   

  // Set this option to true if you want to log messages
  debug: false,

  // Log messages to a specific object (only if debug is true)
  log: console
});

7. Remove highlights manually.

$("#selector").unmark({
  // defaults

  // HTML element to wrap matches, e.g. span
  element: "mark",  

  // A class name that will be appended to element
  className: "",   

  // An array with exclusion selectors. 
  // Elements matching those selectors will be ignored. 
  // Example: "exclude": [".ignore", "*[data-ignore]"]
  exclude: [],

  // Whether to search also inside iframes. 
  // If you don't have permissions to some iframes (e.g. because they have a different origin) they will be silently skipped. 
  // If you don't want to search inside specific iframes (e.g. facebook share), you can pass a filter selector that matches these iframes.
  iframes: false,  

  // The maximum ms to wait for a load event before skipping an iframe. 
  // Especially important when there's no internet connection or a browser "offline" mode is enabled and an iframe has an online src – then the load event is never fired
  iframesTimeout: 5000,

  // As jquery.mark is asynchronous this callback function is called after all marks are completed
  done: function(){},   

  // Set this option to true if you want to log messages
  debug: false,

  // Log messages to a specific object (only if debug is true)
  log: console
})

Changelog:

2018-11-22

  • Fix infinite loop when using the unpublished separateGroups option

2018-11-08

2018-11-07

  • v8.11.1: Keep export logic after build refactoring; Implement separateGroups option

2018-01-09

  • v8.11.0: Update to ESLint 4; Support Vietnamese diacritics

2017-05-13

  • v8.10.1: Update iterator when calling multiple methods on the same instance

2017-05-08

  • v8.10.0: Implement markRanges method

2017-05-05

  • v8.9.1: Fix order in which iframe text nodes are handled

2017-03-12

  • v8.9.0: Implement wildcards option

2017-02-07

  • v8.8.3: Ignore special characters in accuracy complementary 

2017-02-06

  • v8.8.2: Prevent adding empty synonyms

2017-02-05

  • v8.8.1: Fix case insensitive diacritics mapping. And normalize case insensitive diacritics array

2017-01-21

  • v8.8.0: Implement maximum iframe timeout

2017-01-05

  • v8.6.1: Fixed index error when using "acrossElements"

2016-12-29

  • v8.6.0: Allow a string selector as context

2016-12-28

  • v8.5.0: .unmark() performance improvements

2016-12-13

  • v8.4.3: Fix ignoreJoiners with special characters

2016-11-23

  • v8.4.2: Fix ignoreJoiners with special characters

2016-09-15

  • v8.4.0: Implemented ignoreGroups option

2016-09-15

  • v8.3.0: update

2016-09-14

  • v8.2.0: Add Romanian diacritics

2016-09-05

  • v8.1.1: Access only option values from instance options

2016-09-04

  • v8.1.0: Implemented caseSensitive option

2016-09-03

  • v8.0.1: Only wait for iframes when enabled

2016-07-14

  • v7.0.2: Fix CommonJS require export

2016-07-11

  • v7.0.1:  Ignore duplicate context elements

2016-06-20

  • v7.0.0: Implemented new filter callback option

2016-06-12

  • v6.4.0

2016-04-06

  • Fixed mark with multiple same keywords

This awesome jQuery plugin is developed by julmot. For more Advanced Usages, please check the demo page or visit the official website.