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..e953caf962 --- /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. The component searches the content of all nested elements within the ```` tags, and highlights all matches of the specified string. + + +The component searches only DOM text nodes. It does not search 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 via 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 enables case-insensitive matching. 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.

+ +``` + + +This 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 to manipulate its properties: + +```ts +const highlight = document.querySelector('igc-highlight') as IgcHighlightComponent; +``` + +Then, create a function that updates the search text every time the `igcInput` event fires: + +```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 to manipulate its properties. The easiest way to do this is via a reference: + +```tsx +import { useRef } from 'react'; +``` + +```tsx +const highlightRef = useRef(null); +``` + +```tsx + + ... + +``` + +Then, create a function that updates the search text, called every time the `igcInput` event fires: + +```tsx +const onInput = ({ detail }: CustomEvent) => { + highlightRef.current.searchText = detail; +}; +``` + +```tsx + +``` + + +### Methods + +The component also exposes two methods for navigating the search matches. The method moves to the next match, while the method moves to the previous one. + +With them, we can make the search more interactive by adding two buttons to navigate between 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, it 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'}` + : ''; +} +``` + + +We can then call `updateStatus()` every time the input value changes or the user clicks 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 c981ce7297..d9947a4f1e 100644 --- a/docs/xplat/src/content/en/toc.json +++ b/docs/xplat/src/content/en/toc.json @@ -2593,6 +2593,13 @@ "name": "Text Area", "href": "inputs/text-area.md" }, + { + "exclude": [ + "Angular", "Blazor" + ], + "name": "Highlight", + "href": "inputs/highlight.md" + }, { "name": "Interactions", "header": true