Skip to main content

Overview

The getHighlightRanges() function computes non-overlapping highlight ranges for matched tokens in Arabic text. This is a pure, UI-agnostic function that returns character positions and match types, allowing you to control how highlights are rendered in your application.

Function signature

Parameters

string
required
The Arabic text to search for highlights (typically verse.uthmani or verse.standard)
readonly string[] | undefined
required
Array of matched tokens from search results (from verse.matchedTokens). If undefined or empty, returns an empty array.
Record<string, MatchType>
Optional mapping of tokens to their match types (from verse.tokenTypes). If not provided, all tokens default to 'fuzzy' match type.

Return value

array
Array of non-overlapping highlight ranges, sorted by start position
number
Starting character index (0-based) in the text
number
Ending character index (exclusive) in the text
string
The original query token that matched this range
MatchType
The type of match: 'exact', 'lemma', 'root', or 'fuzzy'

Usage

Basic example

React rendering example

This example shows how to render highlighted text in React without using dangerouslySetInnerHTML:

How it works

  1. Token matching: For each matched token, the function creates a regex pattern that:
    • Normalizes Arabic text (handles alef variants, ya/ta marbuta variations)
    • Accounts for optional diacritical marks (tashkeel)
    • Finds all occurrences in the text
  2. Priority sorting: Matches are sorted by:
    • Length (longer matches first) to prioritize more specific matches
    • Start position (earlier matches first) for stable ordering
  3. Overlap resolution: The function ensures non-overlapping ranges by:
    • Processing matches in priority order
    • Marking occupied character positions
    • Skipping matches that overlap with higher-priority matches
  4. Final ordering: Results are sorted by start position for sequential rendering

Notes

  • The function is pure and has no side effects
  • Returns an empty array if matchedTokens is undefined or empty
  • Handles Arabic text variations (alef forms, ya/ta marbuta, etc.)
  • Ignores diacritical marks when matching
  • Guarantees non-overlapping ranges for safe rendering
  • Match types default to 'fuzzy' if tokenTypes is not provided