mark() method

Syntax

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

Parameters:

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

Option	Type	Default	Description
`element`	string	`'mark'`	A custom mark element e.g. `span`.
`className`	string	`''`	A custom class to be added to mark elements.
`exclude`	string or string[]	`[]`	A string or an array of selectors. Specifies DOM elements that should be excluded from searching. See exclude option for more details.
`separateWordSearch`	boolean or string	`true`	A boolean value `true` specifies to break term(s) into separate words and search for each individual word. A string value `'preserveTerms'` preserved term(s) surrounding by double quotes from breaking into separate words. See separateWordSearch option for more details.
`diacritics`	boolean	`true`	Whether to match diacritic characters
`caseSensitive`	boolean	`false`	Whether to search case sensitive
`combineBy`	number	`100`	Combine a specified number of individual term patterns into one (old name `combinePatterns`) See combineBy option for more details.
`accuracy`	string 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 spaces and start/end of a text node content (with `acrossElements` option - start/end of a context). `'startsWith'` e.g. searching 'pre' mark the whole words 'prefix', 'predict', and 'prefab'. `'complementary'` e.g. searching 'a' mark the whole words 'and', 'back', and 'visa'. The built-in boundaries for values `startsWith` and `complementary` are: white spaces and !"#$%&'`()+,-./:;<=>?@[\]^_{\|}~¡¿ characters. See accuracy option for more details. Or an object* with two properties: `value`: `'exactly'` or `'startsWith'` or `'complementary'` `limiters`: a string or an array of custom word boundary characters, e.g. `{ value: 'exactly', limiters: ',.;:?!\'"()' }`
`wildcards`	string	`'disabled'`	Two characters `?` and `` used as wildcards unless they 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.
`ignoreJoiners`	boolean	`false`	Whether to find matches that contain soft hyphen, zero width space, zero width non-joiner and zero width joiner
`ignorePunctuation`	string or string[]	`[]`	A string or an array of punctuation characters
`synonyms`	object	`{}`	An object with synonyms e.g. `{ 'one': '1' }` - '1' is synonym for 'one' and vice versa. The value can be an array, e.g. `{ 'be': ['am', 'is', 'are'] }`. See synonyms option for more details.
`acrossElements`	boolean	`false`	Whether to search for matches across elements See acrossElements option for more details.
`blockElementsBoundary`	boolean or object	`undefined`	Whether 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`.
`highlight`	Highlight	`undefined`	If a `Highlight` object is provided, the library switches to using the `CSS Custom Highlight API` instead of wrapping matches in HTML elements See highlight option for more details.
`highlightName`	string	`'advanced-markjs'`	The name of the `Highlight` object necessary to register it using `HighlightRegistry`
`staticRanges`	boolean	`true`	Whether to use `StaticRange` objects instead of `Range` objects (`Highlight` API) See staticRanges option for more details.
`rangeAcrossElements`	boolean	`true`	Whether to create a single `StaticRange/Range` object for matches located across elements (when using the `Highlight` API with `acrossElements` option) See rangeAcrossElements option for more details.
`shadowDOM`	boolean or object	`undefined`	Whether to mark inside shadow DOMs See shadowDOM option for more details.
`iframes`	boolean or object	`false`	Whether to mark inside iframes See iframes option for more details.
`iframesTimeout`	number	`5000` ms	The maximum time to wait for an iframe to load before skipping
`debug`	boolean	`false`	Whether to log messages
`log`	object	`console`	Log messages to a specific object
`filter`	function		A callback to filter matches. It calls for each match (FAE) filter: (nodeOrArray, term, matchesSoFar, termMatchesSoFar, info) => {} `nodeOrArray` Text or Text[] - The text node which includes the match (TAE) OR an array of text node(s) which include the match if the `Highlight` API is used with `acrossElements` and `rangeAcrossElements` options `term` string - The current term `matchesSoFar` number - The number of all matches so far `termMatchesSoFar` number - The number of matches for the current term so far `info` object: `match` array - The result of RegExp exec() method `count` number - The number of matches so far MC `matchStart` boolean - indicate the start of a match AE `abort` boolean - Setting it to `true` breaks the method execution The function must return either `true` (highlight) or `false` (skip highlighting). See Filtering matches for more details.
`each`	function		A callback for each created element OR `StaticRange/Range` object (`Highlight` API) each: (elementOrRange, info) => {} `elementOrRange` HTMLElement or StaticRange or Range - The marked DOM element OR `StaticRange/Range` object (`Highlight` API) `info` object: `match` array - The result of RegExp exec() method `count` number - The number of matches so far MC `matchStart` boolean - Indicate the start of a match AE `abort` boolean - Setting it to `true` breaks the method execution. See Code examples. Note: the `filter` and `each` callbacks are shared the `info` object with updated properties.
`done`	function		A callback on finish done: (total, totalMatches, termStats) => {} `total` number - The total number of created HTML elements OR `StaticRange/Range` objects (`Highlight` API) `totalMatches` number - The total number of highlighted matches `termStats` object - An object containing an individual term's matches count
`noMatch`	function		A callback that is called when a term has no match at all noMatch: (terms) => {} `terms` string[] - An array containing not found term(s)

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,
    combineBy: 10,
    blockElementsBoundary: false,
    
    staticRanges: true, // Highlight API
    rangeAcrossElements: true, // Highlight API
    shadowDOM: false,
    iframes: false,
    iframesTimeout: 5000,
    
    filter: (nodeOrArray, term, marksSoFar, termMarksSoFar, filterInfo) => {
        return true; // must return either true or false
    },
    each: (elementOrRange, eachInfo) => {},
    done: (total, 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 with the option acrossElements: true

• MC - were already wrapped in HTML elements OR for which were created StaticRange/Range objects

• FAE - with the acrossElements option, if the match is located across several elements, it calls for each text node which is part of the match

• TAE - with the acrossElements option can be part of the match