markRegExp() method

Syntax

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

Parameters:

  • regex RegExp - The regular expression. With acrossElements option it must have g flag - it works with indexes and only two g and y flags allow control RegExp lastIndex.
    Note that for backward compatibility, RegExp without g flag is recompile internally with g flag.
    Although without acrossElements option it doesn't require g flag, it still recommended having this flag for future changes.
  • options object - Optional options:

OptionTypeDefaultDescription
elementstring markA custom mark element e.g. span.
classNamestring '' A custom 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.

See exclude option for more details.

ignoreGroupsnumber 0The number of adjacent capturing groups that should be ignored from the start of RegExp

e.g. /(\w+)(.)(\w+)(?!\2)/g, ignoreGroups : 2 - mark the group 3

separateGroupsboolean falseWhether to mark RegExp capturing groups instead of whole match

See Highlighting separate groups for more details.

acrossElementsboolean falseWhether to search for matches across elements

See acrossElements option for more details.

wrapAllRangesboolean undefinedMark nesting/overlapping capturing groups

See Marking nesting and overlapping ranges and match groups 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, matchString, matchesSoFar, filterInfo) => {}
  • textNode Text - The text node which includes the match or with acrossElements option can be part of the match
  • matchString string - The matching string:
    1. without ignoreGroups and separateGroups options - the whole match
    2. with ignoreGroups option - the match[ignoreGroups+1] group matching string,
      e.g. /(-)(\w+)\s+/g, ignoreGroups : 1, the matching string is content of the group 2
    3. with separateGroups option - the current group matching string
  • matchesSoFar number - The number of all wrapped matches so far
  • filterInfo object:
    • match array - The result of RegExp exec() method
    • matchStart boolean - indicate the start of a match AE
    • groupIndex number - The current group index SG
    • 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.

The function must return either true (to wrap) or false (to skip wrapping mark element).

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 wrapped matches so far
    • groupIndex number - The current index of match group SG
    • groupStart boolean - Indicate the start of group AE SG
donefunction A callback on finish.
done : (totalMarks, totalMatches) => {}
  • totalMarks number - The total number of marked elements
  • totalMatches number - The total number of matches
noMatchfunction A callback that is called when regex failed to match
noMatch : (regex) => {}
  • regex string - The stringify RegExp

Available properties of the filterInfo object depending on options

options match matchStart groupIndex execution offset
acrossElements + + - + +
acrossElements, separateGroups + + + + +
separateGroups + + + + +
above options are false + - - + +

Available properties of the eachInfo object depending on options

options match matchStart groupIndex groupStart count
acrossElements + + - - +
acrossElements, separateGroups + + + + +
separateGroups + + + - +
above options are false + - - - +
Example with default options values 
const options = {
    element : 'mark',
    className : '',
    exclude : [],
    ignoreGroups : 0,
    acrossElements : false,
    wrapAllRanges : false,
    blockElementsBoundary : false,
    shadowDOM : false,
    iframes : false,
    iframesTimeout : 5000,
    filter : (textNode, matchString, matchesSoFar, filterInfo) => {
        return true; // must return either true or false
    },
    each : (markElement, eachInfo) => {},
    done : (totalMarks, totalMatches) => {},
    noMatch : (regex) => {},
    debug : false,
    log : window.console
};

JavaScript:

const instance = new Mark(document.querySelector('selector')),
  regex = /../gi;
instance.markRegExp(regex, options);

jQuery:

$('selector').markRegExp(regex, options);
  • AE - only available when acrossElements option is set to true
  • SG - only available when separateGroups option is set to true
  • AE SG - only available when both acrossElements and separateGroups options are set to true