React component to highlight words within a larger body of text.

Installation

Begin by installing the library from NPM:

npm install react-highlight-words

TypeScript types

TypeScript definitions are included within the published dist folder.

Documentation

Documentation and examples for this project are available at react-highlight-words.vercel.app.

Usage

To use it, just provide it with an array of search terms and a body of text to highlight.

import Highlighter from "react-highlight-words";

function Example() {
  return (
    <Highlighter
      highlightClassName="YourHighlightClass"
      searchWords={["and", "or", "the"]}
      textToHighlight="The dog is chasing the cat. Or perhaps they're just playing?"
    />
  );
}

And the Highlighter will mark all occurrences of search terms within the text:

Highlighter

Highlights all occurrences of one or more search terms within a larger body of text.

Highlighted matches are wrapped in a <mark> element by default, and unhighlighted text is wrapped in a <span>. Both of these can be customized with the highlightTag and unhighlightTag props.

ℹ️ Any other props (such as title or data-* attributes) are applied to the outer/wrapper <span>, and a ref is forwarded to it.

Required props

Name	Description
searchWords	Array of search words. String search terms are matched literally, unless autoEscape is false (in which case they are treated as regular expressions, and strings that aren't valid regular expressions are matched literally). RegExp search terms are used as-is (with their own flags).
textToHighlight	Text to highlight matches in. ℹ️ Browsers collapse whitespace and newlines by default; to preserve them, set the white-space style (e.g. style={{ whiteSpace: "pre-wrap" }}).

Optional props

Name	Description
className	Class name applied to the outer/wrapper <span>.
activeClassName	Class name applied to the active match. ℹ️ Use along with activeIndex.
activeIndex	Index of the match that should be actively highlighted. ℹ️ Use along with activeClassName or activeStyle.
activeStyle	Inline styles applied to the active match. ℹ️ Use along with activeIndex.
autoEscape	Match string search terms literally (defaults to true). Set to false to treat them as regular expressions. (They are compiled without the u flag, so syntax that requires it, such as \p{L}, only works in RegExp search terms.) ⚠️ Only set this to false for trusted search terms; a malicious regular expression can take an extremely long time to run.
caseSensitive	Match string search terms case sensitively. RegExp search terms are case sensitive unless they have the i flag.
findChunks	Custom function to search for matching chunks. This makes it possible to use arbitrary logic when looking for matches. It receives the search options (with defaults applied) and returns the start and end index of each range of text to highlight, along with the searchIndex of the search word that matched it. Overlapping ranges are combined automatically. See the default findChunks function in highlight-words-core for reference.
highlightClassName	Class name applied to highlighted text, or an object mapping search term matches to class names. ℹ️ Object keys are compared with the matched text first, then with the string search term that matched it (case insensitively, unless caseSensitive is true).
highlightStyle	Inline styles applied to highlighted text.
highlightTag	Type of tag to wrap around highlighted matches. Defaults to mark but can also be a React component (class or function). ℹ️ Custom components will receive children, className, highlightIndex, searchIndex, and style props.
sanitize	Process each string search word and the text to highlight before comparing (e.g. to remove accents). Matches always refer to the original text, even if sanitizing changes its length (e.g. "Æ" to "AE"). ℹ️ Sanitizing should transform characters independently; if it changes the text, it is applied to each character separately. RegExp search terms are not sanitized, but they are matched against the sanitized text.
unhighlightClassName	Class name applied to unhighlighted text.
unhighlightStyle	Inline styles applied to unhighlighted text.
unhighlightTag	Type of tag applied to unhighlighted parts of the text. Defaults to span but can also be a React component (class or function).

Custom highlight tag

By default, this component uses an HTML Mark Text element (<mark>) to wrap matched text, but you can inject a custom tag using the highlightTag property. This tag should be a React component that accepts the following properties:

Property	Type	Description
children	String	Text to be highlighted
className	String	Class name(s) to apply
highlightIndex	Number	Index of matched text
searchIndex	Number	Index of the matching search word
style	Object	Inline styles to apply

For example:

import { type HighlightTagProps } from "react-highlight-words";

function Highlight({ children, highlightIndex }: HighlightTagProps) {
  return <strong className="highlighted-text">{children}</strong>;
}

License

MIT License - fork, modify and use however you want.