spotmark

A lightweight, customizable text highlighting library that illuminates matches in a content.


Keywords
highlight, text-highlight, search, match, diacritics, typescript, regex, string-matching, lightweight, zero-dependencies
License
MIT
Install
npm install spotmark@1.0.0

Documentation

Spotmark

npm version License Bundle Size

A tiny but powerful text highlighting library that handles diacritics, punctations, multiple word patterns, and smart text matching. Perfect for search interfaces and text analysis.

Features

  • 🎯 Smart text matching with case-sensitive options and punctuation handling
  • 🌍 Full Unicode support with diacritics (Γ©, Γ , Γ±, etc.)
  • ✨ Flexible search with single or multiple word patterns
  • 🎨 Customizable styling and HTML markup
  • πŸͺΆ Lightweight and framework agnostic

Table of Contents

Installation

To install Spotmark, use npm:

npm install spotmark

or

yarn add spotmark

Usage

Import

// ES6 import
import { createHighlighter } from 'spotmark';

// or CommonJS require
const { createHighlighter } = require('spotmark');

Basic Usage

const text = 'This is a simple but an amazing tool for text highlight 😎.';
const pattern = 'amazing';

const highlight = createHighlighter();
highlight(text, pattern);
β†’ 'This is a simple but an <span class="text-highlight">amazing</span> tool for text highlight 😎.'

Multiple Matches

const text = 'This is a simple but an amazing tool for text highlight 😎.';
const pattern = 'e';

const highlight = createHighlighter();
highlight(text, pattern);
β†’ 'This is a simpl<span class="text-highlight">e</span> but an amazing tool for t<span class="text-highlight">e</span>xt highlight 😎.'

Custom HTML Tag

const text = 'This is a simple but an amazing tool for text highlight 😎.';
const pattern = 'amazing';
const config = { tag: 'mark' };

const highlight = createHighlighter(config);
highlight(text, pattern);
β†’ 'This is a simple but an <mark class="text-highlight">amazing</mark> tool for text highlight 😎.'

Custom Class Name

const text = 'This is a simple but an amazing tool for text highlight 😎.';
const pattern = 'amazing';
const config = { className: 'custom-highlight' };

const highlight = createHighlighter(config);
highlight(text, pattern);
β†’ 'This is a simple but an <span class="custom-highlight">amazing</span> tool for text highlight 😎.'

First Match Only

const text = 'This is a simple but an amazing tool for text highlight 😎.';
const pattern = 'a';
const config = { matchAll: false };

const highlight = createHighlighter(config);
highlight(text, pattern);
β†’ 'This is <span class="text-highlight">a</span> simple but an amazing tool for text highlight 😎.'

Case Sensitive Search

const text = 'This is a simple but an amazing tool for text highlight 😎.';
const pattern = 'AMAZING';
const config = { caseSensitive: true };

const highlight = createHighlighter(config);
highlight(text, pattern);
β†’ 'This is a simple but an amazing tool for text highlight 😎.'

Multiple Words Search

const text = 'This is a simple but an amazing tool for text highlight 😎.';
const pattern = 'simple amazing';
const config = { separateWordSearch: true };

const highlight = createHighlighter(config);
highlight(text, pattern);
β†’ 'This is a <span class="text-highlight">simple</span> but an <span class="text-highlight">amazing</span> tool for text highlight 😎.'

Diacritics Support

const text = 'Je suis allΓ© Γ  la cafΓ©.';
const pattern = 'alle';

const highlight = createHighlighter({ diacritics: true });
highlight(text, pattern);
β†’ 'Je suis <span class="text-highlight">allΓ©</span> Γ  la cafΓ©.'

Ignore Punctuation

const text = "Let's go!";
const pattern = 'Lets';

const highlight = createHighlighter({ ignorePunctuation: true });
highlight(text, pattern);
β†’ "<span class="text-highlight">Let's</span> go!"

API

Functions

createHighlighter(config?: HighlightOptions)

Creates a configured highlighter function. This is the main entry point of the library.

Parameters:

Returns:

  • A highlight function with the following signature:
    (text: string, query: string) => string;

Example:

const highlight = createHighlighter({ caseSensitive: true });

highlight(text: string, query: string)

The function returned by createHighlighter. It performs the actual text highlighting.

Parameters:

  • text: The source text where highlighting will be performed
  • query: The search pattern(s) to highlight

Returns:

  • HTML string with highlighted matches wrapped in configured tags

Example:

const highlighted = highlight('Hello world', 'world'); // Returns: "Hello <span class="text-highlight">world</span>"

Types

HighlightOptions

Configuration options for the highlighter.

Property Type Default Description
caseSensitive boolean false Enables case-sensitive matching
className string 'text-highlight' CSS class applied to highlight wrapper elements
diacritics boolean true Enables matching of text with diacritical marks
ignorePunctuation boolean false Removes punctuation from search consideration
matchAll boolean true Highlights all matches instead of just the first
separateWordSearch boolean true Treats space-separated query words as individual patterns
tag string 'span' HTML tag used for wrapping highlighted matches

Example:

const options: HighlightOptions = {
  caseSensitive: true,
  className: 'custom-highlight',
  tag: 'mark',
};

Styling

To style the wrapped text, you need to add CSS for the default class name text-highlight (or your custom class name if configured).

Example

.text-highlight {
  background-color: yellow;
  color: black;
}

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

License

This project is licensed under the MIT License.