# useSearch

*Category:* Utilities
*Section:* UI state & input hooks
*Source:* https://uikit.developers.rio.cloud/#/utilities/useSearch
*Captured:* 2026-04-27T14:59:44.024Z

The useSearch hook is a custom hook to filter a list of objects by a search value. Supports field-based filtering, custom filtering logic, debounce, and case sensitivity.

## useSearch

### Example: Search a list of objects

Search a list of objects

Apple Banana Fig Pear Mango

#### React (tsx)

```tsx
import { isEmpty } from 'es-toolkit/compat';
import useSearch from '@rio-cloud/rio-uikit/useSearch';
import ClearableInput from '@rio-cloud/rio-uikit/ClearableInput';
import FormLabel from '@rio-cloud/rio-uikit/FormLabel';

export default () => {
    const items = [{ name: 'Apple' }, { name: 'Banana' }, { name: 'Fig' }, { name: 'Pear' }, { name: 'Mango' }];

    const { searchValue, setSearchValue, filteredList } = useSearch(items);

    return (
        <>
            <div className='form-group max-width-300'>
                <FormLabel>Search a list of objects</FormLabel>
                <div className='input-group'>
                    <span className='input-group-addon'>
                        <span className='rioglyph rioglyph-search' aria-hidden='true' />
                    </span>
                    <ClearableInput
                        value={searchValue}
                        onChange={(newValue: string) => setSearchValue(newValue)}
                        onClear={() => setSearchValue('')}
                        placeholder='Search for fruits'
                    />
                </div>
            </div>
            <div className='display-flex gap-10'>
                {isEmpty(filteredList)
                    ? 'Nothing found'
                    : filteredList.map(listItem => <span key={listItem.name}>{listItem.name}</span>)}
            </div>
        </>
    );
};
```

#### HTML (html)

```html
<div class="form-group max-width-300">
    <div class="text-color-dark max-width-100pct text-size-12 display-inline-block margin-bottom-5">Search a list of objects</div>
    <div class="input-group">
        <span class="input-group-addon">
            <span class="rioglyph rioglyph-search" aria-hidden="true">
            </span>
        </span>
        <div class="ClearableInput input-group">
            <input placeholder="Search for fruits" 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 class="display-flex gap-10">
    <span>Apple</span>
    <span>Banana</span>
    <span>Fig</span>
    <span>Pear</span>
    <span>Mango</span>
</div>
```

#### Props: Options for the `useSearch` hook

### Options for the `useSearch` hook

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| list | T[] | — | The array of objects to search through. |
| options | object | — | Configuration options for the search behavior. |
| └fields | (keyof T \| string)[] | — | Fields to search through. If omitted, all top-level string/number fields are used. |
| └customFilter | (item: T, query: string) => boolean | — | Optional custom filter function overriding field-based filtering. |
| └debounceMs | number | — | Debounce time in milliseconds. If omitted, debounce is disabled. |
| └caseSensitive | boolean | false | Whether the search should be case-sensitive. |

#### Props: Return value of the `useSearch` hook

### Return value of the `useSearch` hook

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| searchValue | string | — | The current search input string. |
| setSearchValue | Function | — | A setter function to update the search query. |
| filteredList | T[] | — | The list of items matching the current search query. |

### Example: Search a list of objects for multiple fields

Search a list of objects for multiple fields

Alice - 30 | Berlin
Bob - 25 | Munich
Charlie - 35 |

#### React (tsx)

```tsx
import { isEmpty } from 'es-toolkit/compat';
import useSearch from '@rio-cloud/rio-uikit/useSearch';
import ClearableInput from '@rio-cloud/rio-uikit/ClearableInput';
import FormLabel from '@rio-cloud/rio-uikit/FormLabel';

type ListType = { name: string; age: number; address?: { city: string } };

export default () => {
    const users = [
        { name: 'Alice', age: 30, address: { city: 'Berlin' } },
        { name: 'Bob', age: 25, address: { city: 'Munich' } },
        { name: 'Charlie', age: 35 },
    ];

    const { searchValue, setSearchValue, filteredList } = useSearch(users, { fields: ['name', 'age', 'address.city'] });

    return (
        <>
            <div className='form-group max-width-300'>
                <FormLabel>Search a list of objects for multiple fields</FormLabel>
                <div className='input-group'>
                    <span className='input-group-addon'>
                        <span className='rioglyph rioglyph-search' aria-hidden='true' />
                    </span>
                    <ClearableInput
                        value={searchValue}
                        onChange={(newValue: string) => setSearchValue(newValue)}
                        onClear={() => setSearchValue('')}
                        placeholder='Search for users'
                    />
                </div>
            </div>
            <div>
                {isEmpty(filteredList)
                    ? 'Nothing found'
                    : filteredList.map(listItem => (
                          <div key={listItem.name}>
                              {listItem.name} - {listItem.age} | {listItem.address?.city}
                          </div>
                      ))}
            </div>
        </>
    );
};
```

#### HTML (html)

```html
<div class="form-group max-width-300">
    <div class="text-color-dark max-width-100pct text-size-12 display-inline-block margin-bottom-5">Search a list of objects for multiple fields</div>
    <div class="input-group">
        <span class="input-group-addon">
            <span class="rioglyph rioglyph-search" aria-hidden="true">
            </span>
        </span>
        <div class="ClearableInput input-group">
            <input placeholder="Search for users" 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>Alice - 30 | Berlin</div>
    <div>Bob - 25 | Munich</div>
    <div>Charlie - 35 | </div>
</div>
```

#### Props: Options for the `useSearch` hook

### Options for the `useSearch` hook

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| list | T[] | — | The array of objects to search through. |
| options | object | — | Configuration options for the search behavior. |
| └fields | (keyof T \| string)[] | — | Fields to search through. If omitted, all top-level string/number fields are used. |
| └customFilter | (item: T, query: string) => boolean | — | Optional custom filter function overriding field-based filtering. |
| └debounceMs | number | — | Debounce time in milliseconds. If omitted, debounce is disabled. |
| └caseSensitive | boolean | false | Whether the search should be case-sensitive. |

#### Props: Return value of the `useSearch` hook

### Return value of the `useSearch` hook

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| searchValue | string | — | The current search input string. |
| setSearchValue | Function | — | A setter function to update the search query. |
| filteredList | T[] | — | The list of items matching the current search query. |