<!-- Protocore Design System — Highlight -->
# Highlight

- **Category:** Typography (`typography`)
- **Slug:** `typography/highlight`
- **Status:** stable
- **Platforms:** web
- **Import:** `import { Highlight } from "@protocore/pds";`
- **Docs:** https://pds.protocore.io/components/typography/highlight

> Wraps every occurrence of a substring within text in a tone-tinted Mark — for search results.

## When to use it

`Highlight` is the search-result companion to **Mark**: instead of you slicing the string yourself, it takes the whole text plus the query and marks the hits. Reach for it in command palettes, autocomplete option lists, and result tables.

It only accepts a **plain string** as children — the matching is a pure string operation, which keeps it server-safe and predictable. If you need to highlight inside rich/nested content, compose **Mark** by hand. The term is matched literally (regex metacharacters are escaped), so a query like `a.b` matches the text `a.b`, not `axb`.

## Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `children` | `string` | yes | — | The plain text to render and search within. |
| `className` | `string` | no | — | — |
| `highlight` | `string \| string[]` | yes | — | Substring or substrings to highlight. Empty/blank entries are ignored. |
| `ignoreCase` | `boolean` | no | `true` | Match case-insensitively. |
| `mono` | `boolean` | no | — | Render the text (and marks) in the monospace family. |
| `style` | `CSSProperties` | no | — | — |
| `tone` | `enum` | no | `accent` | Tint applied to each matched run. Defaults to `accent`. |

## Examples

### Basics

Give `Highlight` a string as its children and a `highlight` term; it finds every case-insensitive match and wraps each in a **Mark**, leaving the rest as plain text. This is the canonical way to show what a query matched in a result row.

```tsx
import { Highlight, Text } from "@protocore/pds";

export default function HighlightBasics() {
  return (
    <Text>
      <Highlight highlight="ledger">
        The settlement ledger reconciles every ledger entry against the bank ledger feed.
      </Highlight>
    </Text>
  );
}
```

### Multiple terms

Pass an array of substrings to highlight several terms at once — useful when a search is tokenised into words. Matching is case-insensitive by default; set `ignoreCase={false}` for exact-case matches.

```tsx
import { Highlight, Stack, Text } from "@protocore/pds";

const results = [
  "Protocore ships static customer sites from a unified CMS.",
  "The CMS drives every site as a multi-tenant Payload instance.",
  "Static builds deploy to S3 and CloudFront per domain.",
];

export default function HighlightMultiple() {
  const query = ["static", "cms"];
  return (
    <Stack direction="column" gap={2}>
      {results.map((line, i) => (
        <Text key={i} size="sm">
          <Highlight highlight={query} tone="info">
            {line}
          </Highlight>
        </Text>
      ))}
    </Stack>
  );
}
```

## Usage

**Do**

- Feed it the user's raw query as the `highlight` term.
- Pass an array when the query is several words.
- Keep children a plain string — that's the supported shape.

**Don't**

- Don't pass JSX as children; use `Mark` directly for rich content.
- Don't rely on the highlight alone to convey a match — keep the result readable without colour.
- Don't highlight an empty term expecting the whole string to mark — blank terms are ignored.

## Accessibility

**Notes**

- Each match is a semantic `<mark>`; the surrounding text is untouched, so screen-reader output reads naturally.
- The highlight is a visual cue for sighted users scanning results — the underlying text still communicates the full content.
- Matching escapes regex metacharacters, so user input can never produce a malformed pattern or unexpected matches.

## Related

`mark`, `text`, `search-input`, `combobox`

---

© Protocore. All rights reserved. Use of the Protocore Design System requires prior written authorization from Protocore (contact@protocore.io). These machine-readable materials must not be ingested into ML-training datasets or derivative design systems. See https://pds.protocore.io/legal/