mark() method

Syntax

// javascript
const instance = new Mark(context);
instance.mark(search[, options]);
// jQuery
$(context).mark(search[, options]);

Parameters:

  • search string or string[] - string or array of strings
  • options object - Optional options:

OptionTypeDefaultDescription
elementstring markA custom mark element e.g. span.
classNamestring '' A class to be added to mark elements.
excludestring or string[] []A string or an array of selectors. Specifies DOM elements that should be excluded from searching.
separateWordSearchboolean trueWhether to break term into separate words and search for each individual word
diacriticsboolean trueWhether to match diacritic characters
caseSensitiveboolean falseWhether to search case sensitive
accuracystring or object 'partially'
  • Either one of the following string value:
    • 'partially' e.g. searching 'a' mark 'a' in words 'and', 'back', and 'visa'.
    • 'exactly' This option is actually forced to use an accuracy object, because the default word boundaries are white-space characters and start/end of a text node (with acrossElements option - start/end of a context).
    • 'complementary' e.g. searching 'a' mark the whole words 'and', 'back', and 'visa'. The default word boundaries are: whitespaces and !"#$%&'`()*+,-./:;<=>?@[\]^_{|}~¡¿ characters.
  • Or an bject with two properties:
    • value: 'exactly' or 'complementary'
    • limiters: an array of custom word boundary characters, e.g. { value : "exactly", limiters : ",.;:?!'"".split() }
wildcardsstring disabledTwo characters ? and * used as wildcards unless thay are escaped
  • disabled: The characters ? and * match itself
  • enabled:
    • The character ? match any non-white-space character zero or one time.
    • The character * match any non-white-space character zero or more times.
  • withSpaces:
    • The character ? match any character zero or one time.
    • The character * match any character zero or more times, but as few times as possible.
ignoreJoinersboolean falseWhether to find matches that contain soft hyphen, zero width space, zero width non-joiner and zero width joiner
ignorePunctuationstring[] []An array of punctuation characters
synonymsobject {}An object with synonyms

e.g. { 'one': '1' } - '1' is synonym for 'one' and vice versa. Value can be an array { 'be': ['am', 'is', 'are'] }.

acrossElementsboolean falseWhether to search for matches across elements
combinePatternsnumber or boolean 10Combine a specified number of individual term patterns into one

See Performance for more details.

cacheTextNodesboolean undefinedCaching information to improve performance

See Performance for more details.

blockElementsBoundaryboolean or object undefinedWhether to limit matches within default HTML block elements and/or custom elements

See Elements boundaries for more details.

  • tagNames string[] - An array of custom HTML tag names
  • extend boolean - true extends default boundary elements by the custom elements otherwise only the custom elements do have boundaries
  • char string - A custom boundary character. The default is \x01.
shadowDOMboolean undefinedWhether to mark inside shadow DOMs

See Highlighting in shadow DOM for more details.

iframesboolean falseWhether to mark inside iframes
iframesTimeoutnumber 5000 msThe max time to wait for iframe(s) to load before skipping
debugboolean falseWhether to log messages
logobject consoleLog messages to a specific object
filterfunction A callback to filter matches. It calls for each match (with acrossElements option, if the match is located across several elements, it calls for each text node which is part of the match)
filter : (textNode, term, marksSoFar, termMarksSoFar, filterInfo) => {}
  • textNode Text - The text node which includes the match or with acrossElements option can be part of the match
  • term string - The current term
  • marksSoFar number - The number of all wrapped matches so far
  • termMarksSoFar number - The number of wrapped matches for the current term so far
  • filterInfo object:
    • match array - The result of RegExp exec() method
    • matchStart boolean - indicate the start of a match AE
    • execution object - The helper object for early abort:
      • abort boolean - Setting it to true breaks method execution
    • offset number - When 'acrossElements: false': the absolute start index of a text node in joined context.
      When 'acrossElements: true': the sum of the lengths of separated spaces or boundary strings that were added to the composite string so far.
eachfunction A callback for each marked element
each : (markElement, eachInfo) => {}
  • markElement HTMLElement - The marked DOM element
  • eachInfo object:
    • match array - The result of RegExp exec() method
    • matchStart boolean - Indicate the start of a match AE
    • count number - The number of matches so far
donefunction A callback on finish
done : (totalMarks, totalMatches, termStats) => {}
  • totalMarks number - The total number of marked elements
  • totalMatches number - The total number of matches
  • termStats object - An object containing an individual term's matches count
noMatchfunction A callback that is called when a term has no match at all
noMatch : (term) => {}
  • term string or string[] - The not found term(s); the parameter is array when combinePatterns option is used

Available properties of the filterInfo object depending on options

options match matchStart execution offset
acrossElements: true + + + +
acrossElements: false + - + +

Available properties of the eachInfo object depending on options

options match matchStart count
acrossElements: true + + +
acrossElements: false + - +
Example with default options values 
const options = {
    element : 'mark',
    className : '',
    separateWordSearch : true,
    diacritics : true,
    exclude : [],
    caseSensitive : false,
    accuracy : 'partially',
    synonyms : {},
    ignoreJoiners : false,
    ignorePunctuation : [],
    wildcards : 'disabled',
    
    acrossElements : false,
    combinePatterns : false,
    cacheTextNodes : false,
    blockElementsBoundary : false,
    
    shadowDOM : false,
    iframes : false,
    iframesTimeout : 5000,
    
    filter : (textNode, term, marksSoFar, termMarksSoFar, filterInfo) => {
        return true; // must return either true or false
    },
    each : (markElement, eachInfo) => {},
    done : (totalMarks, totalMatches, termStats) => {},
    noMatch : (term) => {},
    debug : false,
    log : window.console
};

JavaScript:

var instance = new Mark(document.querySelector('selector'));
instance.mark('test', options);

jQuery:

$('selector').mark('test', options);
  • AE - only available when acrossElements option is set to true