Library / SDK
bvaughn/react-highlight-words avatar
bvaughn/react-highlight-words

react-highlight-words: literal matching by default, and a regex switch that the README warns about

React component to highlight words within a larger body of text

2,304 stars175 forksTypeScriptMIT

At a glance

What is it?
bvaughn/react-highlight-words is a TypeScript React component that marks search terms inside a block of text. This article covers how terms are matched, how sanitizing and custom chunk finders work, how highlight tags are replaced, and what the package exports.
Who is it for?
Use react-highlight-words if you need to mark known search terms inside text in a React app and want control over the tags, classes and matching rules. Keep autoEscape at its default for any term that comes from a user, because turning it off hands a person a regular expression engine.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 6 days ago.
What is it written in?
Mainly TypeScript, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 6, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • bvaughn/react-highlight-words2,304 ★ · +1
Star history
Repository2026-10-172026-11-06
bvaughn/react-highlight-words2.3k2.3k

1 Stars in the last 20 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

Highlighter wraps matches in mark and everything else in span

Install with npm:

sh
npm install react-highlight-words

The whole API is one component, `Highlighter`, and the README's example needs only three props:

tsx
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?"
    />
  );
}

Matches are wrapped in a `<mark>` element by default, and unhighlighted text goes in a `<span>`. Both tags can be swapped through `highlightTag` and `unhighlightTag`. Any prop that Highlighter does not know, such as `title` or a `data-*` attribute, lands on the outer wrapper `<span>`, and a `ref` is forwarded to that same element.

The result is a flat run of alternating spans and marks inside one wrapper. That keeps styling simple, because one class on `highlightClassName` reaches every match.

String terms match literally until autoEscape is switched off

`searchWords` takes an array. Each string in it is matched literally by default, so a term like `a.b` finds the three characters `a.b` and not `a` followed by any character. RegExp objects in the array are used as they are, including their own flags.

The `autoEscape` prop controls this. It defaults to `true`. Set it to `false` and string terms are treated as regular expressions, and a string that is not a valid regular expression is matched literally instead of throwing.

Two caveats come with the switch. Strings are compiled without the `u` flag, so syntax that needs it, such as `\p{L}`, works only when you pass a RegExp object yourself. And the README gives a security warning: only set `autoEscape` to `false` for trusted search terms, because a malicious regular expression can take an extremely long time to run.

That warning decides how you wire a search box. If the terms come from what a visitor types, leave `autoEscape` alone. A page where you control the terms, such as a fixed list of keywords, is the safe place for regex mode.

`caseSensitive` handles case for string terms. RegExp terms are case sensitive unless they carry the `i` flag.

highlightClassName can be an object that maps terms to classes

The simple form of `highlightClassName` is one class name for all matches. The README also allows an object that maps search term matches to class names, which lets you color different terms differently.

The lookup order is spelled out: object keys are compared with the matched text first, then with the string search term that matched it. That second comparison is case insensitive unless `caseSensitive` is true. So with a key of `error` and a term `error`, the text `ERROR` in the source still finds its class, as long as case sensitivity is off.

Inline styles have their own props: `highlightStyle` for matches and `unhighlightStyle` for the rest. `className` applies to the outer wrapper span, and `unhighlightClassName` to unhighlighted text.

There is a separate mechanism for an active match, such as the current hit when you step through search results. `activeIndex` is the index of the match to emphasize, and it is used with `activeClassName` or `activeStyle`. Without `activeIndex`, those two props do nothing, so they have to be set as a pair.

sanitize lets accented text match plain terms without moving the match positions

The `sanitize` prop processes each string search word and the text before they are compared. The README's example use is removing accents, so a search for `cafe` can match `café`.

Matches always refer to the original text, even when sanitizing changes its length. The README's example is the character Æ becoming AE: the highlight still covers the original single character.

There is a rule on the function. Sanitizing should transform characters independently. If it changes the text, it is applied to each character separately. A function that depends on neighboring characters, such as one that looks at the next letter, will not behave as you would expect, because it only ever sees one character at a time.

RegExp search terms are not sanitized, but they are matched against the sanitized text. So if your sanitizer strips accents from the text, a regular expression written with accents will no longer find them. Write the pattern for the sanitized form.

findChunks replaces the matching logic and overlapping ranges merge

For matching rules the built-in options cannot express, `findChunks` takes over. It is a custom function that receives the search options with defaults applied. It returns the `start` and `end` index of each range of text to highlight, together with the `searchIndex` of the search word that matched it.

Overlapping ranges that you return are combined automatically, so your function does not have to deduplicate them. The README points to the default `findChunks` function in the highlight-words-core repository as the reference to copy from.

That reference points at the dependency structure. The core matching logic lives in a separate package, `highlight-words-core`, and this package is the React layer on top of it, which is why searches for the package pair the two names. The README does not state the dependency relationship outright, only the link.

Use `findChunks` for fuzzy matching, matching by position, or highlighting ranges that come from somewhere else, such as a server response that already knows which character ranges matched.

A custom highlightTag receives five props, and unhighlightTag can be swapped too

`highlightTag` defaults to `mark` but can be a React component, class or function. A custom component receives five props: `children`, the text to highlight; `className`; `highlightIndex`, the index of the matched text; `searchIndex`, the index of the matching search word; and `style`.

The two index props are the useful ones. `highlightIndex` counts matches in order through the text, and `searchIndex` says which entry in `searchWords` produced the match. A component can use `searchIndex` to pick a color per term without the object form of `highlightClassName`, or use `highlightIndex` to attach an anchor to each hit.

`unhighlightTag` defaults to `span` and can also be a React component. The README lists no prop table for it, so check the behaviour in the documentation site before depending on the props it receives.

The README's custom tag example is cut off in the text available, so the full snippet lives on the documentation site at react-highlight-words.vercel.app, which also hosts the examples.

Whitespace is collapsed by the browser, and the 1.0.0 release arrived the same day as 0.21.1

One behavior surprises people with multi-line text. For `textToHighlight`, the README notes that browsers collapse whitespace and newlines by default. To preserve them, set the `white-space` style, for example `style={{ whiteSpace: "pre-wrap" }}`. The style goes on the wrapper, since extra props land there.

Packaging is clear in package.json. The module type is ESM, with both `dist/react-highlight-words.js` for imports and `dist/react-highlight-words.cjs` for require. TypeScript definitions ship in the published `dist` folder, as `.d.ts` and `.d.cts` files, and `sideEffects` is `false`, so bundlers can drop it when unused. Only `dist` is published.

The release list shows `1.0.0` and `0.21.1`, both on 2026-10-11, about seven hours apart, after `v0.21.0` on 2025-01-12. The last push to `main` was on 2026-10-25, and the repository is not archived. The README does not describe what changed in 1.0.0, so read `CHANGELOG.md` before upgrading from 0.21.

The project builds with Vite and tests with Vitest, using pnpm. Its docs site is built from the same repository.

Editorial conclusion

Use react-highlight-words if you need to mark known search terms inside text in a React app and want control over the tags, classes and matching rules. Keep autoEscape at its default for any term that comes from a user, because turning it off hands a person a regular expression engine. Before shipping, check how the text container handles whitespace, since the component does not preserve line breaks on its own.

Frequently asked questions

What is a highlight text in react-highlight-words?

It is a run of text that matches one of your search terms. The Highlighter component wraps each match in a mark element by default and puts the rest of the text in span elements.

What is React mainly used for, going by react-highlight-words?

The README does not define React. It shows one use: a React component, Highlighter, that takes searchWords and textToHighlight and renders the marked-up text.

Is React hard to learn if I only want react-highlight-words?

The README does not rate difficulty. Basic use is one import and three props, searchWords, textToHighlight and highlightClassName, as in its example.

Official sources

  1. bvaughn/react-highlight-words on GitHub
  2. License: MIT
  3. Project website
  4. README
  5. Releases
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/bvaughn-react-highlight-words.svg)](https://hysenlabs.com/projects/bvaughn-react-highlight-words)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/bvaughn-react-highlight-words.svg)](https://hysenlabs.com/projects/bvaughn-react-highlight-words)

Was this useful?