In CdsAutocomplete, CdsCombobox and CdsSelect the highlighting of the matches is already built in — a standalone CdsHighlight is not needed there. For a permanent label next to the text take CdsTag, for a counter take CdsBadge.

Variations

Search query

The text prop takes the source string, query takes what the user was looking for. The query can be a string or an array of terms: all of them get highlighted.

Sandbox Storybook

<script setup lang="ts">
import { CdsHighlight } from '@central-design-system/components';
</script>

<template>
  <div class="flex flex-col items-center gap-2">
    <CdsHighlight
      class="text-900 text-content-primary"
      text="Шаблоны: договор поставки, договор аренды и договор подряда"
      query="договор"
    />

    <CdsHighlight
      class="text-900 text-content-primary"
      text="Шаблоны: договор поставки, договор аренды и договор подряда"
      :query="['поставки', 'подряда']"
    />
  </div>
</template>

All occurrences

By default the first occurrence of every term is highlighted. The match-all prop highlights all of them — in a long text this shows the full picture.

Sandbox Storybook

<script setup lang="ts">
import { CdsHighlight } from '@central-design-system/components';
</script>

<template>
  <div class="flex flex-col items-center gap-2">
    <CdsHighlight
      class="text-900 text-content-primary"
      text="Шаблоны: договор поставки, договор аренды и договор подряда"
      query="договор"
    />

    <CdsHighlight
      class="text-900 text-content-primary"
      text="Шаблоны: договор поставки, договор аренды и договор подряда"
      query="договор"
      match-all
    />
  </div>
</template>

Case

The ignore-case prop looks for matches regardless of the case. You need it almost always when the query is typed by the user.

Sandbox Storybook

<script setup lang="ts">
import { CdsHighlight } from '@central-design-system/components';
</script>

<template>
  <div class="flex flex-col items-center gap-2">
    <CdsHighlight class="text-900 text-content-primary" text="ИНН, Инн и инн — одно и то же" query="инн" match-all />

    <CdsHighlight
      class="text-900 text-content-primary"
      text="ИНН, Инн и инн — одно и то же"
      query="инн"
      match-all
      ignore-case
    />
  </div>
</template>

Ready ranges

When the matches are found by the server rather than by the browser, pass them into matches — an array of [start, end] pairs by the indexes of the source string. The ranges take precedence over query, and overlapping ones are merged automatically.

Sandbox Storybook

<script setup lang="ts">
import { CdsHighlight } from '@central-design-system/components';

// Диапазоны [start, end] в исходной строке: «канцелярских товаров» и «офиса»
const matches = [
  [28, 48],
  [67, 72]
] as const;
</script>

<template>
  <div class="flex justify-center">
    <CdsHighlight
      class="text-900 text-content-primary"
      text="Заявка на участие в закупке канцелярских товаров для регионального офиса"
      :matches="matches"
    />
  </div>
</template>

Color and density

The color prop sets the color of the highlighting — the background is tinted with it too, so a single value is enough. opacity changes the density of the background.

Sandbox Storybook

<script setup lang="ts">
import { CdsHighlight } from '@central-design-system/components';
</script>

<template>
  <div class="flex flex-col items-center gap-2">
    <CdsHighlight class="text-900 text-content-primary" text="Подсветка цветом по умолчанию" query="по умолчанию" />

    <CdsHighlight
      class="text-900 text-content-primary"
      text="Подсветка цветом бренда"
      query="цветом бренда"
      color="brand-primary"
    />

    <CdsHighlight
      class="text-900 text-content-primary"
      text="Более плотный фон подсветки"
      query="плотный фон"
      color="green"
      opacity="28%"
    />
  </div>
</template>

Markup

The tag prop sets the tag of the wrapper (span by default), mark-class adds your own class to every match.

Sandbox Storybook

<script setup lang="ts">
import { CdsHighlight } from '@central-design-system/components';
</script>

<template>
  <div class="flex flex-col items-center gap-2">
    <CdsHighlight
      class="text-900 text-content-primary"
      tag="p"
      text="Подсветка внутри абзаца: тег задаётся пропом tag"
      query="внутри абзаца"
    />

    <CdsHighlight
      class="text-900 text-content-primary"
      text="Совпадению можно добавить свой класс"
      query="свой класс"
      mark-class="font-bold"
    />
  </div>
</template>

Guidelines

Storybook

Scenarios

Searching through a list

The same query filters the list and highlights the matches in the found rows. match-all and ignore-case keep the highlighting and the filter consistent: once a row made it into the results, the match inside it is visible.

Sandbox Storybook

<script setup lang="ts">
import { CdsHighlight, CdsTextInput } from '@central-design-system/components';
import { computed, ref } from 'vue';

const query = ref('дог');

const documents = [
  'Договор поставки канцелярии',
  'Договор аренды помещения',
  'Акт сверки взаиморасчётов',
  'Счёт на оплату № 1024'
];

const found = computed(() => {
  const needle = query.value.trim().toLowerCase();

  return needle ? documents.filter((document) => document.toLowerCase().includes(needle)) : documents;
});
</script>

<template>
  <div class="flex w-[350px] flex-col gap-2 m-auto">
    <CdsTextInput v-model="query" placeholder="Поиск по документам" prepend-inner-icon="search" clearable />

    <ul class="m-0 flex list-none flex-col gap-1 p-0">
      <li v-for="document in found" :key="document">
        <CdsHighlight
          class="text-900 text-content-primary"
          :text="document"
          :query="query.trim()"
          match-all
          ignore-case
        />
      </li>

      <li v-if="found.length === 0" class="text-900 text-content-secondary">Ничего не найдено</li>
    </ul>
  </div>
</template>

A query of several words

Split the typed phrase into words and pass them as an array into query — the component highlights every word separately, even if they stand far apart in the text.

Sandbox Storybook

<script setup lang="ts">
import { CdsHighlight, CdsTextInput } from '@central-design-system/components';
import { computed, ref } from 'vue';

const query = ref('бумага а4');

const description =
  'Закупка бумаги: бумага А4 плотностью 80 г/м², бумага А3 и картон. Поставка на склад в Москве до конца месяца.';

const terms = computed(() => query.value.trim().split(/\s+/).filter(Boolean));
</script>

<template>
  <div class="flex w-[350px] flex-col gap-2 m-auto">
    <CdsTextInput v-model="query" label="Запрос" placeholder="Например: бумага а4" clearable />

    <CdsHighlight
      class="text-900 text-content-primary"
      tag="p"
      :text="description"
      :query="terms"
      match-all
      ignore-case
    />
  </div>
</template>

Matches from the server

The full-text search on the backend already knows which fragments count as matches: it accounts for morphology, synonyms and typos. Give those ranges to matches — the client will not search anything again.

Sandbox Storybook

<script setup lang="ts">
import { CdsButton, CdsHighlight } from '@central-design-system/components';
import { ref } from 'vue';

interface SearchResult {
  id: number;
  title: string;
  matches: [number, number][];
}

const loading = ref(false);
const results = ref<SearchResult[]>([]);

// Ответ поиска: сервер сам решил, какие фрагменты считать совпадениями
const response: SearchResult[] = [
  { id: 1, title: 'Заявка на поставку бумаги А4 для офиса', matches: [[19, 28]] },
  { id: 2, title: 'Договор поставки бумаги и картона', matches: [[17, 23]] }
];

const search = () => {
  loading.value = true;
  results.value = [];

  setTimeout(() => {
    results.value = response;
    loading.value = false;
  }, 1200);
};
</script>

<template>
  <div class="flex w-[350px] flex-col gap-2 m-auto">
    <CdsButton text="Найти «бумага А4»" :loading="loading" @click="search" />

    <ul class="m-0 flex list-none flex-col gap-1 p-0">
      <li v-for="result in results" :key="result.id">
        <CdsHighlight class="text-900 text-content-primary" :text="result.title" :matches="result.matches" />
      </li>
    </ul>
  </div>
</template>

API

Props

Name	Type	Default	Description
color	string | undefined	—	Color of the highlighted text.
ignoreCase	boolean | undefined	—	Ignores the case when searching by query.
markClass	string | undefined	—	Extra CSS class for the <mark> element.
matchAll	boolean | undefined	—	Highlights every occurrence, not just the first one.
matches	readonly MatchRange[] | undefined	—	Ready match ranges [start, end]. They take precedence over query.
opacity	string | number | undefined	—	Opacity of the highlight background (the --cds-highlight-opacity CSS variable).
query	string | string[] | undefined	—	Search query: a string or an array of term strings.
tag	string | JSXComponent<any> | undefined	'span'	Custom HTML tag or component to render
text	string | undefined	''	The text the highlighting is performed in.