bvaughn/react-highlight-words

README

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  element by default, and unhighlighted text is wrapped in a . 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 , and a ref is forwarded to it.

Required props

Name Description

searchWords

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" }}`).

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 () 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.