toHighlight
Pure transformer that splits text into matched and unmatched chunks. Returns a plain HighlightChunk[] — wrap the call in computed() for reactive recomputation.
Usage
import { computed } from 'vue'
import { toHighlight } from '@vuetify/v0'
const chunks = computed(() =>
toHighlight(() => props.text, () => props.query, { ignoreCase: true })
)
// chunks.value → [{ text: 'Hello ', match: false }, { text: 'World', match: true }]Architecture
toHighlight resolves its input through a fixed priority order:
Reactivity
toHighlight is a pure transformer — it reads each input through toValue once and returns a plain HighlightChunk[]. To make the result track upstream changes, wrap the call in computed() (or any reactive scope). The function itself creates no reactivity.
| Behavior | Reactive | Notes |
|---|---|---|
Calling toHighlight(text, query) | One-shot snapshot at call time | |
Wrapping in computed(() => toHighlight(...)) | Re-runs when tracked refs change | |
| Passing refs or getters as arguments | toValue unwraps them on every call | |
| Mutating returned chunks | Treat the array as derived; do not mutate |
Reach for plain values, refs, or getters Every input accepts MaybeRefOrGetter<T>. Pass a literal for static input, a Ref for v-model integration, or a getter (() => props.text) for prop-driven reactivity. Wrap the call in computed() when you want the result to update automatically.
Examples
Accessibility
Wrap matched chunks in the native <mark> element. It carries the implicit ARIA role mark and is announced by screen readers as highlighted or marked text. No additional ARIA attributes are needed on the wrapper element.
WCAG 1.4.3 (Contrast — Minimum) applies to highlighted text. Ensure sufficient contrast between the mark background color and the surrounding text.
FAQ
Yes. The source text string is sliced at match boundaries, so the original characters (including casing, punctuation, and whitespace) are always preserved in the output chunks. ignoreCase affects only the matching logic, not the returned text.
Yes. The matches option accepts MatchRange[] — [start, end] pairs. Once createFilter exposes positional data, pass the result directly and skip the query path.
Overlapping or adjacent spans are merged before the chunks array is produced. ['foo', 'oba'] against 'foobar' yields [{ text: 'fooba', match: true }, { text: 'r', match: false }] rather than two separate matches.
Yes. Ranges passed via the matches option are sorted by start index and merged on overlap or adjacency before chunking. Pass [[4, 6], [0, 2]] or [[0, 4], [2, 6]] and the output is the same as if you had supplied the canonical sorted, non-overlapping form.
The function returns a single [{ text: sourceText, match: false }] chunk — the full string with no highlights. Safe to iterate without any guard.
Yes. toHighlight is a pure function with no DOM access and no reactive state. It is safe to call during SSR.