Highlight Match

Marks what was typed inside a search result, so the eye lands on why each row matched. The search lists use it on their own; reach for it directly in custom rows and find-in-text.

Installation#

# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add highlight-match

Usage#

usage.tsxTSX

import { HighlightMatch } from "@/components/ui/highlight-match"

export function Example() {
  return <HighlightMatch query="head">Page header</HighlightMatch>
}

Anatomy#

import { HighlightMatch } from "@/components/ui/highlight-match"

<HighlightMatch query="…">Text to search in</HighlightMatch>

In search lists#

Command, Combobox, Autocomplete and Select Search mark the plain text of every row as you type. Icons, shortcuts and badges pass through untouched. Matching folds accents and case the way the filters do, so co finds Córdoba and zu finds Zürich. Turn it off with highlightMatches={false}.

Nested labels#

Only a row's top-level text is marked for you. When the label sits inside its own markup, wrap it in a bare <HighlightMatch>: it reads the query from the list around it, secondary lines included.

Find in text#

The same layer works over prose and over headings that are already bold, and keeps its rounding when a match wraps onto the next line. Pass the query yourself when there is no search list around it.

Data retention

Records are kept for the retention period set by each workspace and deleted when it ends.

Access to records

Members can request a copy of the records held about them at any time, free of charge.

Deleting a workspace

Deleting a workspace removes its records after a thirty day grace period.

API reference#

HighlightMatch

Splits its text around every match and wraps each one in a native <mark>. Accepts className, merged last onto each mark.

Prop	Type	Default	Description
children	string \| number	-	The text to search in. Anything else renders untouched.
query	string	-	What was typed. Defaults to the query of the Command, Combobox or Select Search around it. Each word is matched on its own; accents and case are ignored.
variant	"fill" \| "weight"	"fill"	`fill` lays a faint ink layer behind the match and keeps the weight, so nothing reflows as you type. `weight` sets it in semibold full ink with no layer, for a surface that can't take another fill.

Command · Combobox · Autocomplete · SelectSearch

The search lists mark their rows' text with no extra code.

Prop	Type	Default	Description
highlightMatches	boolean	true	Marks the query in each row's top-level text. A row that nests its label marks it with a bare `<HighlightMatch>`.

matchRanges

(text, query) => [start, end][]. The merged ranges HighlightMatch draws, for a renderer of your own (a canvas, a virtualized grid cell).

FAQ#

A layer marks the match without changing the weight, so the letters never widen and the row never reflows as you type. It is a translucent tint of the theme's own ink, so it stays one step off whatever sits under it, the active row's wash included, in every theme.