@rio-cloud/uikit-mcp 1.1.5 → 1.1.7

package/dist/docs/utilities/useSearchHighlight.md

@@ -0,0 +1,815 @@
+# useSearchHighlight
+
+*Category:* Utilities
+*Section:* UI state & input hooks
+*Source:* https://uikit.developers.rio.cloud/#/utilities/useSearchHighlight
+*Captured:* 2026-02-23T15:50:00.718Z
+
+The useSearchHighlight hook applies native CSS Highlight API ranges to matching text in a referenced container. It progressively enhances supported browsers without mutating markup and can be scoped or made case-sensitive as needed.
+
+## useSearchHighlight
+
+For simple cases, the <SearchHighlightText> component wraps the hook and provides amark fallback when the Highlight API is unavailable.
+
+Use it when you just need to highlight a single string without managing refs or DOM scopes. For complex layouts (tables, lists, or rich markup), prefer useSearchHighlight so you can target a container and control when highlights refresh.
+
+### Example: Example 1
+
+Shipments8
+
+Shipment idOriginDestinationStatus
+
+RIO-100284Hamburg, DERotterdam, NLIn transit
+RIO-100317Berlin, DEPrague, CZDelivered
+RIO-100411Munich, DEVienna, ATDelayed
+RIO-100512Cologne, DEParis, FRCustoms
+RIO-100640Leipzig, DEZurich, CHIn transit
+RIO-100771Stuttgart, DEMilan, ITDelivered
+RIO-100889Frankfurt, DEWarsaw, PLIn transit
+RIO-101002Dresden, DECopenhagen, DKDelayed
+
+Case-sensitive search
+
+#### Summary
+
+Shipments8
+
+Shipment idOriginDestinationStatus
+
+RIO-100284Hamburg, DERotterdam, NLIn transit
+RIO-100317Berlin, DEPrague, CZDelivered
+RIO-100411Munich, DEVienna, ATDelayed
+RIO-100512Cologne, DEParis, FRCustoms
+RIO-100640Leipzig, DEZurich, CHIn transit
+RIO-100771Stuttgart, DEMilan, ITDelivered
+RIO-100889Frankfurt, DEWarsaw, PLIn transit
+RIO-101002Dresden, DECopenhagen, DKDelayed
+
+Case-sensitive search
+
+#### React (tsx)
+
+```tsx
+import { useRef, useState } from 'react';
+
+import Checkbox from '@rio-cloud/rio-uikit/Checkbox';
+import TableSearch from '@rio-cloud/rio-uikit/TableSearch';
+import useSearch from '@rio-cloud/rio-uikit/useSearch';
+import useSearchHighlight from '@rio-cloud/rio-uikit/useSearchHighlight';
+
+type ShipmentStatus = 'In transit' | 'Delivered' | 'Delayed' | 'Customs';
+
+type LogisticsRow = {
+    shipmentId: string;
+    origin: string;
+    destination: string;
+    status: ShipmentStatus;
+};
+
+const tableData: LogisticsRow[] = [
+    { shipmentId: 'RIO-100284', origin: 'Hamburg, DE', destination: 'Rotterdam, NL', status: 'In transit' },
+    { shipmentId: 'RIO-100317', origin: 'Berlin, DE', destination: 'Prague, CZ', status: 'Delivered' },
+    { shipmentId: 'RIO-100411', origin: 'Munich, DE', destination: 'Vienna, AT', status: 'Delayed' },
+    { shipmentId: 'RIO-100512', origin: 'Cologne, DE', destination: 'Paris, FR', status: 'Customs' },
+    { shipmentId: 'RIO-100640', origin: 'Leipzig, DE', destination: 'Zurich, CH', status: 'In transit' },
+    { shipmentId: 'RIO-100771', origin: 'Stuttgart, DE', destination: 'Milan, IT', status: 'Delivered' },
+    { shipmentId: 'RIO-100889', origin: 'Frankfurt, DE', destination: 'Warsaw, PL', status: 'In transit' },
+    { shipmentId: 'RIO-101002', origin: 'Dresden, DE', destination: 'Copenhagen, DK', status: 'Delayed' },
+];
+
+export default () => {
+    const tableBodyRef = useRef<HTMLTableSectionElement | null>(null);
+    const [isCaseSensitive, setIsCaseSensitive] = useState(false);
+
+    const { searchValue, setSearchValue, filteredList } = useSearch<LogisticsRow>(tableData, {
+        fields: ['shipmentId', 'origin', 'destination', 'status'],
+        debounceMs: 100,
+        caseSensitive: isCaseSensitive,
+    });
+
+    // progressive enhancement – always safe to call
+    useSearchHighlight({
+        ref: tableBodyRef,
+        query: searchValue,
+        caseSensitive: isCaseSensitive,
+        deps: [filteredList],
+    });
+
+    return (
+        <div className='padding-15'>
+            {/* table toolbar */}
+            <div className='table-toolbar'>
+                <div className='table-toolbar-container'>
+                    <div className='table-toolbar-group-left'>
+                        <div className='table-toolbar-column'>
+                            <div className='display-flex gap-10 align-items-center'>
+                                <span className='text-medium'>Shipments</span>
+                                <span className='label label-muted label-filled'>{filteredList.length}</span>
+                            </div>
+                        </div>
+                    </div>
+
+                    <div className='table-toolbar-group-right'>
+                        <div className='table-toolbar-column'>
+                            <TableSearch
+                                value={searchValue}
+                                onChange={setSearchValue}
+                                onClear={() => setSearchValue('')}
+                                placeholder='Search in table'
+                            />
+                        </div>
+                    </div>
+                </div>
+            </div>
+
+            {/* table */}
+            <div className='table-responsive'>
+                <table className='table table-bordered table-head-filled'>
+                    <thead>
+                        <tr>
+                            <th>Shipment id</th>
+                            <th>Origin</th>
+                            <th>Destination</th>
+                            <th>Status</th>
+                        </tr>
+                    </thead>
+
+                    <tbody ref={tableBodyRef}>
+                        {filteredList.map(row => (
+                            <tr key={row.shipmentId}>
+                                <td>{row.shipmentId}</td>
+                                <td>{row.origin}</td>
+                                <td>{row.destination}</td>
+                                <td>{row.status}</td>
+                            </tr>
+                        ))}
+
+                        {!filteredList.length && (
+                            <tr>
+                                <td colSpan={4} className='text-center text-color-gray padding-25'>
+                                    No matching shipments
+                                </td>
+                            </tr>
+                        )}
+                    </tbody>
+                </table>
+            </div>
+
+            <div className='margin-top-10'>
+                <Checkbox
+                    checked={isCaseSensitive}
+                    onChange={event => setIsCaseSensitive((event.target as HTMLInputElement).checked)}
+                >
+                    Case-sensitive search
+                </Checkbox>
+            </div>
+        </div>
+    );
+};
+```
+
+#### HTML (html)
+
+```html
+<div class="padding-15">
+    <div class="table-toolbar">
+        <div class="table-toolbar-container">
+            <div class="table-toolbar-group-left">
+                <div class="table-toolbar-column">
+                    <div class="display-flex gap-10 align-items-center">
+                        <span class="text-medium">Shipments</span>
+                        <span class="label label-muted label-filled">8</span>
+                    </div>
+                </div>
+            </div>
+            <div class="table-toolbar-group-right">
+                <div class="table-toolbar-column">
+                    <div class="table-toolbar-search input-group">
+                        <span class="input-group-addon">
+                            <span class="rioglyph rioglyph-search">
+                            </span>
+                        </span>
+                        <div class="ClearableInput input-group">
+                            <input placeholder="Search in table" class="form-control" type="text" tabindex="0" value="">
+                            <span class="clearButton hide">
+                                <span class="clearButtonIcon rioglyph rioglyph-remove-sign">
+                                </span>
+                            </span>
+                        </div>
+                    </div>
+                </div>
+            </div>
+        </div>
+    </div>
+    <div class="table-responsive">
+        <table class="table table-bordered table-head-filled">
+            <thead>
+                <tr>
+                    <th>Shipment id</th>
+                    <th>Origin</th>
+                    <th>Destination</th>
+                    <th>Status</th>
+                </tr>
+            </thead>
+            <tbody>
+                <tr>
+                    <td>RIO-100284</td>
+                    <td>Hamburg, DE</td>
+                    <td>Rotterdam, NL</td>
+                    <td>In transit</td>
+                </tr>
+                <tr>
+                    <td>RIO-100317</td>
+                    <td>Berlin, DE</td>
+                    <td>Prague, CZ</td>
+                    <td>Delivered</td>
+                </tr>
+                <tr>
+                    <td>RIO-100411</td>
+                    <td>Munich, DE</td>
+                    <td>Vienna, AT</td>
+                    <td>Delayed</td>
+                </tr>
+                <tr>
+                    <td>RIO-100512</td>
+                    <td>Cologne, DE</td>
+                    <td>Paris, FR</td>
+                    <td>Customs</td>
+                </tr>
+                <tr>
+                    <td>RIO-100640</td>
+                    <td>Leipzig, DE</td>
+                    <td>Zurich, CH</td>
+                    <td>In transit</td>
+                </tr>
+                <tr>
+                    <td>RIO-100771</td>
+                    <td>Stuttgart, DE</td>
+                    <td>Milan, IT</td>
+                    <td>Delivered</td>
+                </tr>
+                <tr>
+                    <td>RIO-100889</td>
+                    <td>Frankfurt, DE</td>
+                    <td>Warsaw, PL</td>
+                    <td>In transit</td>
+                </tr>
+                <tr>
+                    <td>RIO-101002</td>
+                    <td>Dresden, DE</td>
+                    <td>Copenhagen, DK</td>
+                    <td>Delayed</td>
+                </tr>
+            </tbody>
+        </table>
+    </div>
+    <div class="margin-top-10">
+        <label class="checkbox" tabindex="0">
+            <input type="checkbox" class="">
+            <span class="checkbox-text">
+                <span>Case-sensitive search</span>
+            </span>
+        </label>
+    </div>
+</div>
+```
+
+#### Props: useSearchHighlight
+
+### useSearchHighlight
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| ref | React.RefObject<HTMLElement> | — | Ref to the element whose text content should be searched. |
+| query | string | — | Search query used for highlighting. |
+| highlightClassName | string | 'search-result-highlight' | Name of the CSS highlight. |
+| scopeSelector | string | — | Optional selector to limit the search scope (e.g. '.ListMenuGroup' or '.OptionLabel'). |
+| caseSensitive | boolean | false | Whether to perform a case-sensitive match. |
+| deps | unknown[] | — | Optional dependencies that should trigger re-collecting and applying ranges. Useful when the DOM changes after the query changes (e.g. debounced filtering). |
+
+#### Props: SearchHighlightText
+
+### SearchHighlightText
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| text | string | — | Full text content to render and highlight. |
+| query | string | — | Search query used to highlight matches within the text. |
+| caseSensitive | boolean | false | Whether to perform a case-sensitive match. |
+| highlightClassName | string | 'search-result-highlight' | Optional CSS highlight class name (used by the Highlight API). |
+| classNames | string | — | Optional additional classes applied to the wrapper element. |
+
+### Example: Example 2
+
+Shipments8
+
+RIO-100284
+In transit
+Origin: Hamburg, DE
+Destination: Rotterdam, NL
+
+RIO-100317
+Delivered
+Origin: Berlin, DE
+Destination: Prague, CZ
+
+RIO-100411
+Delayed
+Origin: Munich, DE
+Destination: Vienna, AT
+
+RIO-100512
+Customs
+Origin: Cologne, DE
+Destination: Paris, FR
+
+RIO-100640
+In transit
+Origin: Leipzig, DE
+Destination: Zurich, CH
+
+RIO-100771
+Delivered
+Origin: Stuttgart, DE
+Destination: Milan, IT
+
+RIO-100889
+In transit
+Origin: Frankfurt, DE
+Destination: Warsaw, PL
+
+RIO-101002
+Delayed
+Origin: Dresden, DE
+Destination: Copenhagen, DK
+
+#### Summary
+
+Shipments8
+
+RIO-100284
+In transit
+Origin: Hamburg, DE
+Destination: Rotterdam, NL
+
+RIO-100317
+Delivered
+Origin: Berlin, DE
+Destination: Prague, CZ
+
+RIO-100411
+Delayed
+Origin: Munich, DE
+Destination: Vienna, AT
+
+RIO-100512
+Customs
+Origin: Cologne, DE
+Destination: Paris, FR
+
+RIO-100640
+In transit
+Origin: Leipzig, DE
+Destination: Zurich, CH
+
+RIO-100771
+Delivered
+Origin: Stuttgart, DE
+Destination: Milan, IT
+
+RIO-100889
+In transit
+Origin: Frankfurt, DE
+Destination: Warsaw, PL
+
+RIO-101002
+Delayed
+Origin: Dresden, DE
+Destination: Copenhagen, DK
+
+#### React (tsx)
+
+```tsx
+import { useRef } from 'react';
+
+import TableSearch from '@rio-cloud/rio-uikit/TableSearch';
+import useSearch from '@rio-cloud/rio-uikit/useSearch';
+import useSearchHighlight from '@rio-cloud/rio-uikit/useSearchHighlight';
+
+type ShipmentStatus = 'In transit' | 'Delivered' | 'Delayed' | 'Customs';
+
+type LogisticsRow = {
+    shipmentId: string;
+    origin: string;
+    destination: string;
+    status: ShipmentStatus;
+};
+
+const listData: LogisticsRow[] = [
+    { shipmentId: 'RIO-100284', origin: 'Hamburg, DE', destination: 'Rotterdam, NL', status: 'In transit' },
+    { shipmentId: 'RIO-100317', origin: 'Berlin, DE', destination: 'Prague, CZ', status: 'Delivered' },
+    { shipmentId: 'RIO-100411', origin: 'Munich, DE', destination: 'Vienna, AT', status: 'Delayed' },
+    { shipmentId: 'RIO-100512', origin: 'Cologne, DE', destination: 'Paris, FR', status: 'Customs' },
+    { shipmentId: 'RIO-100640', origin: 'Leipzig, DE', destination: 'Zurich, CH', status: 'In transit' },
+    { shipmentId: 'RIO-100771', origin: 'Stuttgart, DE', destination: 'Milan, IT', status: 'Delivered' },
+    { shipmentId: 'RIO-100889', origin: 'Frankfurt, DE', destination: 'Warsaw, PL', status: 'In transit' },
+    { shipmentId: 'RIO-101002', origin: 'Dresden, DE', destination: 'Copenhagen, DK', status: 'Delayed' },
+];
+
+export default () => {
+    const listRef = useRef<HTMLUListElement | null>(null);
+
+    const { searchValue, setSearchValue, filteredList } = useSearch<LogisticsRow>(listData, {
+        fields: ['shipmentId', 'origin', 'destination', 'status'],
+        debounceMs: 150,
+        caseSensitive: false,
+    });
+
+    // progressive enhancement – always safe to call
+    useSearchHighlight({
+        ref: listRef,
+        query: searchValue,
+        deps: [filteredList],
+    });
+
+    return (
+        <div className='padding-15'>
+            <div className='table-toolbar'>
+                <div className='table-toolbar-container'>
+                    <div className='table-toolbar-group-left'>
+                        <div className='table-toolbar-column'>
+                            <div className='display-flex gap-10 align-items-center'>
+                                <span className='text-medium'>Shipments</span>
+                                <span className='label label-muted label-filled'>{filteredList.length}</span>
+                            </div>
+                        </div>
+                    </div>
+
+                    <div className='table-toolbar-group-right'>
+                        <div className='table-toolbar-column'>
+                            <TableSearch
+                                value={searchValue}
+                                onChange={setSearchValue}
+                                onClear={() => setSearchValue('')}
+                                placeholder='Search in list'
+                            />
+                        </div>
+                    </div>
+                </div>
+            </div>
+
+            <ul ref={listRef} className='list-group border rounded'>
+                {filteredList.map(row => (
+                    <li className='list-group-item' key={row.shipmentId}>
+                        <div className='display-flex align-items-center gap-15'>
+                            <div className='height-50 width-50 bg-lightest rounded-circle display-grid place-items-center'>
+                                <div className='text-size-14 text-color-darkest'>
+                                    <span className='rioglyph rioglyph-order text-size-h2' />
+                                </div>
+                            </div>
+                            <div className='flex-1-1 margin-bottom-5'>
+                                <div className='display-flex flex-wrap justify-content-between align-items-center gap-10'>
+                                    <div className='text-medium'>{row.shipmentId}</div>
+                                    <span className='label label-muted label-filled'>{row.status}</span>
+                                </div>
+                                <div className='text-color-gray'>
+                                    <span className='text-color-darker'>Origin:</span> {row.origin}
+                                </div>
+                                <div className='text-color-gray'>
+                                    <span className='text-color-darker'>Destination:</span> {row.destination}
+                                </div>
+                            </div>
+                        </div>
+                    </li>
+                ))}
+
+                {!filteredList.length && (
+                    <li className='list-group-item text-center text-color-gray padding-25'>No matching shipments</li>
+                )}
+            </ul>
+        </div>
+    );
+};
+```
+
+#### HTML (html)
+
+```html
+<div class="padding-15">
+    <div class="table-toolbar">
+        <div class="table-toolbar-container">
+            <div class="table-toolbar-group-left">
+                <div class="table-toolbar-column">
+                    <div class="display-flex gap-10 align-items-center">
+                        <span class="text-medium">Shipments</span>
+                        <span class="label label-muted label-filled">8</span>
+                    </div>
+                </div>
+            </div>
+            <div class="table-toolbar-group-right">
+                <div class="table-toolbar-column">
+                    <div class="table-toolbar-search input-group">
+                        <span class="input-group-addon">
+                            <span class="rioglyph rioglyph-search">
+                            </span>
+                        </span>
+                        <div class="ClearableInput input-group">
+                            <input placeholder="Search in list" class="form-control" type="text" tabindex="0" value="">
+                            <span class="clearButton hide">
+                                <span class="clearButtonIcon rioglyph rioglyph-remove-sign">
+                                </span>
+                            </span>
+                        </div>
+                    </div>
+                </div>
+            </div>
+        </div>
+    </div>
+    <ul class="list-group border rounded">
+        <li class="list-group-item">
+            <div class="display-flex align-items-center gap-15">
+                <div class="height-50 width-50 bg-lightest rounded-circle display-grid place-items-center">
+                    <div class="text-size-14 text-color-darkest">
+                        <span class="rioglyph rioglyph-order text-size-h2">
+                        </span>
+                    </div>
+                </div>
+                <div class="flex-1-1 margin-bottom-5">
+                    <div class="display-flex flex-wrap justify-content-between align-items-center gap-10">
+                        <div class="text-medium">RIO-100284</div>
+                        <span class="label label-muted label-filled">In transit</span>
+                    </div>
+                    <div class="text-color-gray">
+                        <span class="text-color-darker">Origin:</span> Hamburg, DE
+                    </div>
+                    <div class="text-color-gray">
+                        <span class="text-color-darker">Destination:</span> Rotterdam, NL
+                    </div>
+                </div>
+            </div>
+        </li>
+        <li class="list-group-item">
+            <div class="display-flex align-items-center gap-15">
+                <div class="height-50 width-50 bg-lightest rounded-circle display-grid place-items-center">
+                    <div class="text-size-14 text-color-darkest">
+                        <span class="rioglyph rioglyph-order text-size-h2">
+                        </span>
+                    </div>
+                </div>
+                <div class="flex-1-1 margin-bottom-5">
+                    <div class="display-flex flex-wrap justify-content-between align-items-center gap-10">
+                        <div class="text-medium">RIO-100317</div>
+                        <span class="label label-muted label-filled">Delivered</span>
+                    </div>
+                    <div class="text-color-gray">
+                        <span class="text-color-darker">Origin:</span> Berlin, DE
+                    </div>
+                    <div class="text-color-gray">
+                        <span class="text-color-darker">Destination:</span> Prague, CZ
+                    </div>
+                </div>
+            </div>
+        </li>
+        <li class="list-group-item">
+            <div class="display-flex align-items-center gap-15">
+                <div class="height-50 width-50 bg-lightest rounded-circle display-grid place-items-center">
+                    <div class="text-size-14 text-color-darkest">
+                        <span class="rioglyph rioglyph-order text-size-h2">
+                        </span>
+                    </div>
+                </div>
+                <div class="flex-1-1 margin-bottom-5">
+                    <div class="display-flex flex-wrap justify-content-between align-items-center gap-10">
+                        <div class="text-medium">RIO-100411</div>
+                        <span class="label label-muted label-filled">Delayed</span>
+                    </div>
+                    <div class="text-color-gray">
+                        <span class="text-color-darker">Origin:</span> Munich, DE
+                    </div>
+                    <div class="text-color-gray">
+                        <span class="text-color-darker">Destination:</span> Vienna, AT
+                    </div>
+                </div>
+            </div>
+        </li>
+        <li class="list-group-item">
+            <div class="display-flex align-items-center gap-15">
+                <div class="height-50 width-50 bg-lightest rounded-circle display-grid place-items-center">
+                    <div class="text-size-14 text-color-darkest">
+                        <span class="rioglyph rioglyph-order text-size-h2">
+                        </span>
+                    </div>
+                </div>
+                <div class="flex-1-1 margin-bottom-5">
+                    <div class="display-flex flex-wrap justify-content-between align-items-center gap-10">
+                        <div class="text-medium">RIO-100512</div>
+                        <span class="label label-muted label-filled">Customs</span>
+                    </div>
+                    <div class="text-color-gray">
+                        <span class="text-color-darker">Origin:</span> Cologne, DE
+                    </div>
+                    <div class="text-color-gray">
+                        <span class="text-color-darker">Destination:</span> Paris, FR
+                    </div>
+                </div>
+            </div>
+        </li>
+        <li class="list-group-item">
+            <div class="display-flex align-items-center gap-15">
+                <div class="height-50 width-50 bg-lightest rounded-circle display-grid place-items-center">
+                    <div class="text-size-14 text-color-darkest">
+                        <span class="rioglyph rioglyph-order text-size-h2">
+                        </span>
+                    </div>
+                </div>
+                <div class="flex-1-1 margin-bottom-5">
+                    <div class="display-flex flex-wrap justify-content-between align-items-center gap-10">
+                        <div class="text-medium">RIO-100640</div>
+                        <span class="label label-muted label-filled">In transit</span>
+                    </div>
+                    <div class="text-color-gray">
+                        <span class="text-color-darker">Origin:</span> Leipzig, DE
+                    </div>
+                    <div class="text-color-gray">
+                        <span class="text-color-darker">Destination:</span> Zurich, CH
+                    </div>
+                </div>
+            </div>
+        </li>
+        <li class="list-group-item">
+            <div class="display-flex align-items-center gap-15">
+                <div class="height-50 width-50 bg-lightest rounded-circle display-grid place-items-center">
+                    <div class="text-size-14 text-color-darkest">
+                        <span class="rioglyph rioglyph-order text-size-h2">
+                        </span>
+                    </div>
+                </div>
+                <div class="flex-1-1 margin-bottom-5">
+                    <div class="display-flex flex-wrap justify-content-between align-items-center gap-10">
+                        <div class="text-medium">RIO-100771</div>
+                        <span class="label label-muted label-filled">Delivered</span>
+                    </div>
+                    <div class="text-color-gray">
+                        <span class="text-color-darker">Origin:</span> Stuttgart, DE
+                    </div>
+                    <div class="text-color-gray">
+                        <span class="text-color-darker">Destination:</span> Milan, IT
+                    </div>
+                </div>
+            </div>
+        </li>
+        <li class="list-group-item">
+            <div class="display-flex align-items-center gap-15">
+                <div class="height-50 width-50 bg-lightest rounded-circle display-grid place-items-center">
+                    <div class="text-size-14 text-color-darkest">
+                        <span class="rioglyph rioglyph-order text-size-h2">
+                        </span>
+                    </div>
+                </div>
+                <div class="flex-1-1 margin-bottom-5">
+                    <div class="display-flex flex-wrap justify-content-between align-items-center gap-10">
+                        <div class="text-medium">RIO-100889</div>
+                        <span class="label label-muted label-filled">In transit</span>
+                    </div>
+                    <div class="text-color-gray">
+                        <span class="text-color-darker">Origin:</span> Frankfurt, DE
+                    </div>
+                    <div class="text-color-gray">
+                        <span class="text-color-darker">Destination:</span> Warsaw, PL
+                    </div>
+                </div>
+            </div>
+        </li>
+        <li class="list-group-item">
+            <div class="display-flex align-items-center gap-15">
+                <div class="height-50 width-50 bg-lightest rounded-circle display-grid place-items-center">
+                    <div class="text-size-14 text-color-darkest">
+                        <span class="rioglyph rioglyph-order text-size-h2">
+                        </span>
+                    </div>
+                </div>
+                <div class="flex-1-1 margin-bottom-5">
+                    <div class="display-flex flex-wrap justify-content-between align-items-center gap-10">
+                        <div class="text-medium">RIO-101002</div>
+                        <span class="label label-muted label-filled">Delayed</span>
+                    </div>
+                    <div class="text-color-gray">
+                        <span class="text-color-darker">Origin:</span> Dresden, DE
+                    </div>
+                    <div class="text-color-gray">
+                        <span class="text-color-darker">Destination:</span> Copenhagen, DK
+                    </div>
+                </div>
+            </div>
+        </li>
+    </ul>
+</div>
+```
+
+#### Props: useSearchHighlight
+
+### useSearchHighlight
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| ref | React.RefObject<HTMLElement> | — | Ref to the element whose text content should be searched. |
+| query | string | — | Search query used for highlighting. |
+| highlightClassName | string | 'search-result-highlight' | Name of the CSS highlight. |
+| scopeSelector | string | — | Optional selector to limit the search scope (e.g. '.ListMenuGroup' or '.OptionLabel'). |
+| caseSensitive | boolean | false | Whether to perform a case-sensitive match. |
+| deps | unknown[] | — | Optional dependencies that should trigger re-collecting and applying ranges. Useful when the DOM changes after the query changes (e.g. debounced filtering). |
+
+#### Props: SearchHighlightText
+
+### SearchHighlightText
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| text | string | — | Full text content to render and highlight. |
+| query | string | — | Search query used to highlight matches within the text. |
+| caseSensitive | boolean | false | Whether to perform a case-sensitive match. |
+| highlightClassName | string | 'search-result-highlight' | Optional CSS highlight class name (used by the Highlight API). |
+| classNames | string | — | Optional additional classes applied to the wrapper element. |
+
+## SearchHighlightText
+
+### Example: Example 3
+
+Highlight in textShipment RIO-100284 departed Hamburg, DE and is scheduled to arrive in Rotterdam, NL. The next leg routes through Cologne, DE with customs clearance pending. Contact the logistics desk for status updates or delays.
+
+#### Summary
+
+Highlight in textShipment RIO-100284 departed Hamburg, DE and is scheduled to arrive in Rotterdam, NL. The next leg routes through Cologne, DE with customs clearance pending. Contact the logistics desk for status updates or delays.
+
+#### React (tsx)
+
+```tsx
+import { useState } from 'react';
+
+import SearchHighlightText from '@rio-cloud/rio-uikit/SearchHighlightText';
+
+const logisticsText =
+    'Shipment RIO-100284 departed Hamburg, DE and is scheduled to arrive in Rotterdam, NL. ' +
+    'The next leg routes through Cologne, DE with customs clearance pending. ' +
+    'Contact the logistics desk for status updates or delays.';
+
+export default () => {
+    const [searchValue, setSearchValue] = useState('');
+
+    return (
+        <div className='padding-15 max-width-800'>
+            <label className='text-medium margin-bottom-5' htmlFor='highlight-search'>
+                Highlight in text
+            </label>
+            <input
+                id='highlight-search'
+                className='form-control margin-bottom-15'
+                value={searchValue}
+                onChange={event => setSearchValue(event.target.value)}
+                placeholder='Search text'
+            />
+
+            <div className='panel panel-default panel-body margin-bottom-0'>
+                <SearchHighlightText text={logisticsText} query={searchValue} />
+            </div>
+        </div>
+    );
+};
+```
+
+#### HTML (html)
+
+```html
+<div class="padding-15 max-width-800">
+    <label class="text-medium margin-bottom-5" for="highlight-search">Highlight in text</label>
+    <input id="highlight-search" class="form-control margin-bottom-15" placeholder="Search text" value="">
+    <div class="panel panel-default panel-body margin-bottom-0">
+        <span class="">Shipment RIO-100284 departed Hamburg, DE and is scheduled to arrive in Rotterdam, NL. The next leg routes through Cologne, DE with customs clearance pending. Contact the logistics desk for status updates or delays.</span>
+    </div>
+</div>
+```
+
+#### Props: useSearchHighlight
+
+### useSearchHighlight
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| ref | React.RefObject<HTMLElement> | — | Ref to the element whose text content should be searched. |
+| query | string | — | Search query used for highlighting. |
+| highlightClassName | string | 'search-result-highlight' | Name of the CSS highlight. |
+| scopeSelector | string | — | Optional selector to limit the search scope (e.g. '.ListMenuGroup' or '.OptionLabel'). |
+| caseSensitive | boolean | false | Whether to perform a case-sensitive match. |
+| deps | unknown[] | — | Optional dependencies that should trigger re-collecting and applying ranges. Useful when the DOM changes after the query changes (e.g. debounced filtering). |
+
+#### Props: SearchHighlightText
+
+### SearchHighlightText
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| text | string | — | Full text content to render and highlight. |
+| query | string | — | Search query used to highlight matches within the text. |
+| caseSensitive | boolean | false | Whether to perform a case-sensitive match. |
+| highlightClassName | string | 'search-result-highlight' | Optional CSS highlight class name (used by the Highlight API). |
+| classNames | string | — | Optional additional classes applied to the wrapper element. |