HighlightBuilder - DyeLight

The HighlightBuilder provides a convenient API for building highlight configurations for the DyeLight component. It includes methods for creating character-level highlights, line-level highlights, pattern-based highlights, and more.

import { HighlightBuilder } from 'dyelight';

const highlights = HighlightBuilder.pattern(
  code,
  /\b(const|let|var)\b/g,
  'keyword'
);

Methods

ranges

Creates character range highlights using absolute positions.

ranges(
  ranges: Array<{
    start: number;
    end: number;
    className?: string;
    style?: React.CSSProperties;
  }>
): CharacterRange[]

Parameters:

ranges - Array of character range configurations
- start - Zero-based start index (inclusive)
- end - Zero-based end index (exclusive)
- className - Optional CSS class name to apply
- style - Optional inline styles to apply

Returns: Array of character range highlights Example:

// Highlight specific ranges in the text
const highlights = HighlightBuilder.ranges([
  { start: 0, end: 5, className: 'title-highlight' },
  { start: 10, end: 20, style: { backgroundColor: 'yellow' } },
  { start: 25, end: 30, className: 'error-highlight' }
]);

<DyeLight value={text} highlights={highlights} />

pattern

Highlights text matching a regular expression or string pattern using absolute positions.

pattern(
  text: string,
  pattern: RegExp | string,
  className?: string,
  style?: React.CSSProperties
): CharacterRange[]

Parameters:

text - The text to search within
pattern - Regular expression or string pattern to match (automatically converted to global regex)
className - Optional CSS class name to apply to matches
style - Optional inline styles to apply to matches

Returns: Array of character range highlights for all matches Example:

// Highlight all JavaScript keywords
const keywordHighlights = HighlightBuilder.pattern(
  code,
  /\b(function|const|let|var|if|else|for|while)\b/g,
  'keyword-highlight'
);

// Highlight all email addresses
const emailHighlights = HighlightBuilder.pattern(
  text,
  /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b/g,
  'email-highlight'
);

// Highlight with inline styles
const todoHighlights = HighlightBuilder.pattern(
  text,
  /TODO:/g,
  undefined,
  { backgroundColor: 'orange', fontWeight: 'bold' }
);

words

Highlights entire words that match specific terms.

words(
  text: string,
  words: string[],
  className?: string,
  style?: React.CSSProperties
): CharacterRange[]

Parameters:

text - The text to search within
words - Array of words to highlight (matched as whole words using word boundaries)
className - Optional CSS class name to apply to matched words
style - Optional inline styles to apply to matched words

Returns: Array of character range highlights for all matched words Example:

// Highlight specific programming keywords
const highlights = HighlightBuilder.words(
  sourceCode,
  ['function', 'const', 'let', 'var', 'return'],
  'keyword'
);

// Highlight important terms with custom styling
const termHighlights = HighlightBuilder.words(
  document,
  ['TODO', 'FIXME', 'NOTE'],
  undefined,
  { backgroundColor: 'orange', fontWeight: 'bold' }
);

<DyeLight value={sourceCode} highlights={highlights} />

characters

Creates highlights for individual characters using absolute positions.

characters(
  chars: Array<{
    index: number;
    className?: string;
    style?: React.CSSProperties;
  }>
): CharacterRange[]

Parameters:

chars - Array of character highlight configurations
- index - Zero-based character index in the text
- className - Optional CSS class name to apply
- style - Optional inline styles to apply

Returns: Array of character range highlights Example:

// Highlight characters at positions 5, 10, and 15
const highlights = HighlightBuilder.characters([
  { index: 5, className: 'highlight-error' },
  { index: 10, className: 'highlight-warning' },
  { index: 15, style: { backgroundColor: 'yellow' } }
]);

// Highlight error markers in code
const errorPositions = [42, 108, 256];
const errorHighlights = HighlightBuilder.characters(
  errorPositions.map(pos => ({ index: pos, className: 'error-marker' }))
);

selection

Highlights text between specific start and end positions. Convenience method for highlighting a single selection range.

selection(
  start: number,
  end: number,
  className?: string,
  style?: React.CSSProperties
): CharacterRange[]

Parameters:

start - Zero-based start index (inclusive)
end - Zero-based end index (exclusive)
className - Optional CSS class name to apply
style - Optional inline styles to apply

Returns: Array containing a single character range highlight Example:

// Highlight a selection from position 10 to 25
const selectionHighlight = HighlightBuilder.selection(
  10,
  25,
  'selection-highlight'
);

// Highlight search results
function SearchHighlight({ text, searchTerm }) {
  const [selectedIndex, setSelectedIndex] = useState(0);
  const matches = text.matchAll(new RegExp(searchTerm, 'gi'));
  const positions = Array.from(matches, m => m.index!);

  const allHighlights = HighlightBuilder.pattern(
    text,
    new RegExp(searchTerm, 'gi'),
    'search-match'
  );

  const activeHighlight = positions[selectedIndex]
    ? HighlightBuilder.selection(
        positions[selectedIndex],
        positions[selectedIndex] + searchTerm.length,
        'active-search-match'
      )
    : [];

  return (
    <DyeLight
      value={text}
      highlights={[...allHighlights, ...activeHighlight]}
    />
  );
}

lines

Creates line highlights for entire lines.

lines(
  lines: Array<{
    line: number;
    className?: string;
    color?: string;
  }>
): { [lineNumber: number]: string }

Parameters:

lines - Array of line highlight configurations
- line - Zero-based line number
- className - Optional CSS class name to apply to the line
- color - Optional color value (CSS color, hex, rgb, etc.)

Returns: Object mapping line numbers to highlight values Example:

// Highlight lines 0 and 2 with different styles
const lineHighlights = HighlightBuilder.lines([
  { line: 0, className: 'error-line' },
  { line: 2, color: '#ffff00' }
]);

<DyeLight value={code} lineHighlights={lineHighlights} />

// Highlight current line and error lines
function CodeEditor({ code, currentLine, errorLines }) {
  const lineHighlights = HighlightBuilder.lines([
    { line: currentLine, className: 'current-line' },
    ...errorLines.map(line => ({ line, className: 'error-line' }))
  ]);

  return <DyeLight value={code} lineHighlights={lineHighlights} />;
}

Combining highlights

You can combine multiple highlight methods to create complex highlighting patterns:

function SyntaxHighlighter({ code }) {
  const highlights = [
    // Keywords
    ...HighlightBuilder.pattern(code, /\b(function|const|let|var|return|if|else)\b/g, 'keyword'),
    
    // Strings
    ...HighlightBuilder.pattern(code, /"[^"]*"|'[^']*'/g, 'string'),
    
    // Numbers
    ...HighlightBuilder.pattern(code, /\b\d+\b/g, 'number'),
    
    // Function names
    ...HighlightBuilder.pattern(code, /\b[a-zA-Z_][a-zA-Z0-9_]*(?=\()/g, 'function-name'),
    
    // Comments
    ...HighlightBuilder.pattern(code, /\/\/.*$/gm, 'comment'),
  ];

  const lineHighlights = HighlightBuilder.lines([
    { line: 0, className: 'current-line' }
  ]);

  return (
    <DyeLight
      value={code}
      highlights={highlights}
      lineHighlights={lineHighlights}
    />
  );
}

Performance considerations

When using HighlightBuilder with large texts:

The pattern() method performs a full text scan - consider debouncing when used in onChange handlers
Overlapping highlights are automatically handled, but minimizing overlaps improves performance
For very large documents (>100KB), consider virtualizing or limiting highlight ranges to visible areas
Use useMemo to cache highlight calculations when the text hasn’t changed:

function Editor({ code, onChange }) {
  const highlights = useMemo(
    () => HighlightBuilder.pattern(code, /\b(const|let|var)\b/g, 'keyword'),
    [code]
  );

  return <DyeLight value={code} onChange={onChange} highlights={highlights} />;
}

Documentation Index

​Methods

​ranges

​pattern

​words

​characters

​selection

​lines

​Combining highlights

​Performance considerations

Methods

ranges

pattern

words

characters

selection

lines

Combining highlights

Performance considerations