spotmark

Spotmark

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
• Usage
• API
• Configuration
• Styling
• Contributing
• License

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:

• config: Optional configuration object (see HighlightOptions)

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.