From 3d1aad530aa27c1a420a67f08d8a023f364b3da6 Mon Sep 17 00:00:00 2001 From: Adrian Petrov Date: Wed, 20 May 2026 18:22:06 +0300 Subject: [PATCH] docs(): add highlight article --- .../en/components/inputs/highlight.mdx | 412 ++++++++++++++++++ docs/xplat/src/content/en/toc.json | 7 + 2 files changed, 419 insertions(+) create mode 100644 docs/xplat/src/content/en/components/inputs/highlight.mdx diff --git a/docs/xplat/src/content/en/components/inputs/highlight.mdx b/docs/xplat/src/content/en/components/inputs/highlight.mdx new file mode 100644 index 0000000000..b2273c4a48 --- /dev/null +++ b/docs/xplat/src/content/en/components/inputs/highlight.mdx @@ -0,0 +1,412 @@ +--- +title: {Platform} Highlight | Infragistics +_description: Infragistics' {Platform} Highlight component allows you to search for specific text in the page content and highlight it. +_keywords: {Platform}, UI controls, web widgets, UI widgets, {Platform} Highlight Components, Infragistics +_license: MIT +mentionedTypes: ["Highlight"] +--- +import PlatformBlock from 'igniteui-astro-components/components/mdx/PlatformBlock.astro'; +import Sample from 'igniteui-astro-components/components/mdx/Sample.astro'; +import ApiLink from 'igniteui-astro-components/components/mdx/ApiLink.astro'; +import DocsAside from 'igniteui-astro-components/components/mdx/DocsAside.astro'; + +# {Platform} Highlight Overview + +{ProductName} Highlight is used to highlight parts of the page content to make it more noticeable for the user. It's a lightweight component that can be used in combination with other components to create a more interactive and engaging user experience. + +
+ +## Usage + +To use the component, all you need to do is wrap its tags around the content you want to search through. The component searches through the content of all nested elements within the ```` tags, and highlights all matches of the specified string. + + +The component searches only through DOM text nodes. It does not search through input values or content set via the CSS `content` property. + + +First, you need to install the {ProductName} by running the following command: + + +```cmd +npm install {PackageWebComponents} +``` + +You will then need to import the component, its necessary CSS, and register its module, like so: + +```ts +import { defineComponents, IgcHighlightComponent } from 'igniteui-webcomponents'; +import 'igniteui-webcomponents/themes/light/bootstrap.css'; + +defineComponents(IgcHighlightComponent); +``` + + + +```cmd +npm install igniteui-react +``` + +You will then need to import the and its necessary CSS, like so: + +```tsx +import { IgrHighlight } from 'igniteui-react'; +import 'igniteui-webcomponents/themes/light/bootstrap.css'; +``` + + +For a complete introduction to the {ProductName}, read the [**Getting Started**](../general-getting-started.md) topic. + +The simplest way to start using the component is as follows: + + +```html + +

Lorem ipsum dolor sit, amet consectetur adipisicing elit.

+ +``` + +The `` tags wrap the content in which you want to highlight the specific string. + + + +```tsx + +

Lorem ipsum dolor sit, amet consectetur adipisicing elit.

+ +``` + +The `` tags wrap the content in which you want to highlight the specific string. + + +The text to be highlighted is set through the attribute. In the example above, the word "dolor" will be highlighted. + + + +### Case Sensitive Match + +The component also exposes a attribute. Its default value is `false`, which returns case-insensitive matches. By setting it to `true` you can enable case-sensitive matching. + +The following snippet: + + +```html + +

Lorem ipsum dolor sit, amet consectetur adipisicing elit.

+ +``` + + + +```tsx + +

Lorem ipsum dolor sit, amet consectetur adipisicing elit.

+ +``` + + +Returns 0 matches because the search text "lorem" is in lowercase, while the text in the content is **Lorem** with an uppercase **L**. + +### Using Highlight with a Search Input + +The most common use case is binding the component to a search component, so that search matches are highlighted in real time as the user types. + +To bind the two together you can listen to the `igcInput` event of the component and set the attribute of the component to the input value every time the event is fired (you can also use the standard `input` event). + + +First you need to access the component so you can manipulate its properties: + +```ts +const highlight = document.querySelector('igc-highlight') as IgcHighlightComponent; +``` + +Then create a function that updates the search text every time the input value changes through the `igcInput` event: + +```ts +const onInput = ({ detail }: CustomEvent) => { + highlight.searchText = detail; +}; + +document.querySelector('igc-input')?.addEventListener('igcInput', onInput); +``` + +```html + + +

+ Lorem ipsum dolor sit, amet consectetur adipisicing elit. Quae doloribus odit id excepturi ipsum provident eaque dignissimos beatae! +

+ +``` + + + +First you need to access the component so you can manipulate its properties, the easiest way to do that is through a reference: + +```tsx +import { useRef } from 'react'; +``` + +```tsx +const highlightRef = useRef(null); +``` + +```tsx + + ... + +``` + +Then create a function that will update the status of the search, which will be called every time the value of the search input changes through the `igcInput` event: + +```tsx +const onInput = ({ detail }: CustomEvent) => { + highlightRef.current.searchText = detail; +}; +``` + +```tsx + +``` + + +### Methods + +The component also exposes two methods that allow you to navigate through the matches of the searched text. The method will navigate to the next match, while the method will navigate to the previous match. + +With them we can make the search more interactive by creating two buttons that will allow you to navigate through the matches: + + +```ts +const highlight = document.querySelector('igc-highlight') as IgcHighlightComponent; + +const prev = () => { + highlight.previous(); +}; + +const next = () => { + highlight.next(); +}; + +document.querySelector('#prev-btn')?.addEventListener('click', prev); +document.querySelector('#next-btn')?.addEventListener('click', next); +``` + + + +```tsx +const highlightRef = useRef(null); + +const prev = () => { + highlightRef.current?.previous(); +}; + +const next = () => { + highlightRef.current?.next(); +}; +``` + + + +```html + + + + + + ... + +``` + + + +```tsx + + + + +``` + + + + +Both the and methods accept a option that prevents the page from scrolling to the active match during navigation. By default, the option is set to `false`. + + +```ts +const prev = () => { + highlight.previous({ preventScroll: true }); +}; + +const next = () => { + highlight.next({ preventScroll: true }); +}; +``` + + + +```tsx +const prev = () => { + highlightRef.current?.previous({ preventScroll: true }); +}; + +const next = () => { + highlightRef.current?.next({ preventScroll: true }); +}; +``` + + +### Additional Features + +The component also exposes two read-only properties for tracking match state: returns the total number of matches, and returns the index of the active match. + +They are useful for building a search status indicator that shows the user which match they are on and how many matches exist in total. + +Here is a simple example of how to use those properties to create a search status: + + +```ts +const highlight = document.querySelector('igc-highlight') as IgcHighlightComponent; +const status = document.querySelector('#helper-text') as HTMLParagraphElement; + +const updateStatus = () => { + status.textContent = highlight.size + ? `${highlight.current + 1} of ${highlight.size} match${highlight.size === 1 ? '' : 'es'}` + : ''; +} +``` + + + +```tsx +const highlightRef = useRef(null); +const statusRef = useRef(null); + +const updateStatus = () => { + const highlight = highlightRef.current; + const status = statusRef.current; + + status.textContent = highlight.size + ? `${highlight.current + 1} of ${highlight.size} match${highlight.size === 1 ? '' : 'es'}` + : ''; +} +``` + + +Then we can call the `updateStatus()` function every time the value of the search input changes and every time the user clicks on the next or previous buttons: + + +```ts +const onInput = ({ detail }: CustomEvent) => { + highlight.searchText = detail; + updateStatus(); +}; + +const prev = () => { + highlight.previous(); + updateStatus(); +}; + +const next = () => { + highlight.next(); + updateStatus(); +}; + +document.querySelector('igc-input')?.addEventListener('igcInput', onInput); +document.querySelector('#prev-btn')?.addEventListener('click', prev); +document.querySelector('#next-btn')?.addEventListener('click', next); +``` + +```html + + + +

+ + + ... + +``` + + + +```tsx +const onInput = ({ detail }: CustomEvent) => { + highlightRef.current.searchText = detail; + updateStatus(); +}; + +const prev = () => { + highlightRef.current?.previous(); + updateStatus(); +}; + +const next = () => { + highlightRef.current?.next(); + updateStatus(); +}; +``` + +```tsx + + + +

+ + + +``` + + + + +## Styling + +The component exposes four CSS variables which can be used to style the whole component: +- `--foreground` The text color for a highlighted text node. +- `--background` The background color for a highlighted text node. +- `--foreground-active` The text color for the active highlighted text node. +- `--background-active` The background color for the active highlighted text node. + +```css +igc-highlight { + --background: var(--ig-gray-700); + --foreground: var(--ig-gray-700-contrast); + --background-active: var(--ig-warn-500); + --foreground-active: var(--ig-warn-500-contrast); +} +``` + + + +## API References + + + +## Additional Resources + +- [{ProductName} **Forums**]({ForumsLink}) +- [{ProductName} **GitHub**]({GithubLink}) diff --git a/docs/xplat/src/content/en/toc.json b/docs/xplat/src/content/en/toc.json index 879292c8c7..e792551670 100644 --- a/docs/xplat/src/content/en/toc.json +++ b/docs/xplat/src/content/en/toc.json @@ -2531,6 +2531,13 @@ "name": "Text Area", "href": "inputs/text-area.md" }, + { + "exclude": [ + "Angular", "Blazor" + ], + "name": "Highlight", + "href": "inputs/highlight.md" + }, { "name": "Interactions", "header": true