react-highlight-words

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"]}
      autoEscape={true}
      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>.

Required props

Name	Description
searchWords	Array of search words. String search terms are automatically cast to RegExps unless autoEscape is true.
textToHighlight	Text to highlight matches in.

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	Escape characters in searchWords that are meaningful in regular expressions.
caseSensitive	Match search terms case sensitively.
findChunks	Custom function to search for matching chunks. This makes it possible to use arbitrary logic when looking for matches. See the default findChunks function in highlight-words-core for its signature.
highlightClassName	Class name applied to highlighted text, or an object mapping search term matches to class names.
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, and style props.
sanitize	Process each search word and the text to highlight before comparing (e.g. to remove accents).
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
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.