Highlight Words Core

1.2.3 · maintenance · verified Sun Apr 19

highlight-words-core is a foundational utility library that provides core logic for identifying and segmenting matching words within a larger text string. It serves as the headless engine for UI components like `react-highlight-words` and `react-native-highlight-words`, abstracting away the text processing logic. The current stable version is 1.2.3. As a low-level utility, its release cadence is infrequent, primarily receiving updates for critical bug fixes or performance enhancements rather than new features. Its key differentiator is its framework-agnostic nature, allowing developers to implement custom rendering logic on top of its chunking output, making it versatile for various highlighting applications beyond specific UI frameworks.

Common errors

```
Uncaught SyntaxError: Invalid regular expression: /[+]/:
```
cause A special regular expression character in `searchWords` was not escaped, leading to an invalid regex pattern at runtime.

fix Ensure `autoEscape: true` is passed to `findAll` when `searchWords` are dynamically generated or come from user input.
```
Highlights are not appearing for expected matches.
```
cause This is often due to a mismatch in case sensitivity or incorrect `searchWords` values. By default, searches are case-insensitive.

fix Verify that `searchWords` contains the correct terms. If exact case matches are needed, set `caseSensitive: true` in the `findAll` options.

Warnings

gotcha When `searchWords` are user-supplied, special regular expression characters (e.g., '.', '*', '+', '?', '(', ')', '[', ']', '{', '}', '\', '|', '^', '$') can cause `findAll` to throw a `SyntaxError: Invalid regular expression` if not properly escaped. Always set `autoEscape: true` for dynamic search terms.
Fix: Pass `autoEscape: true` to the `findAll` function options: `findAll({ searchWords, textToHighlight, autoEscape: true })`.
gotcha The `caseSensitive` option defaults to `false`, meaning searches are case-insensitive. If exact case matching is required, this option must be explicitly set to `true`.
Fix: Set `caseSensitive: true` in the `findAll` function options: `findAll({ searchWords, textToHighlight, caseSensitive: true })`.
gotcha The package currently ships with JavaScript files, but type declarations are provided separately by `@types/highlight-words-core`. Developers using TypeScript need to install both packages to get type support.
Fix: Install TypeScript types: `npm install --save-dev @types/highlight-words-core` in addition to `npm install highlight-words-core`.

Install

npm install highlight-words-core npm
yarn add highlight-words-core yarn
pnpm add highlight-words-core pnpm

Imports

findAll
wrong:
```
const findAll = require('highlight-words-core');
```
correct:
```
import { findAll } from 'highlight-words-core';
```
The package primarily uses named exports and is intended for modern JavaScript environments. While CommonJS might work via transpilation, direct CommonJS require statements are not idiomatic.

Quickstart

Demonstrates how to use `findAll` to process text and produce HTML with highlighted matches, including options for `autoEscape` and `caseSensitive`.

import { findAll } from 'highlight-words-core';

const textToHighlight = 'This is some text to highlight.';
const searchWords = ['This', 'i', 'highlight.'];

// Find all occurrences of searchWords in textToHighlight
const chunks = findAll({
  searchWords,
  textToHighlight,
  autoEscape: true, // Recommended for user-provided search terms
  caseSensitive: false // Set to true for exact case matches
});

// Example of how to render the highlighted text in a web context
const highlightedHtml = chunks
  .map(chunk => {
    const { end, highlight, start } = chunk;
    const text = textToHighlight.substring(start, end);
    if (highlight) {
      return `<mark style="background-color: yellow;">${text}</mark>`;
    } else {
      return text;
    }
  })
  .join('');

console.log(highlightedHtml); // Outputs: <mark style="background-color: yellow;">This</mark> is some text to <mark style="background-color: yellow;">highlight.</mark>

view raw JSON →