# @open-pioneer/search

> This package provides a UI component to perform a search on given search sources.

Latest version **1.7.0** (published 2026-11-19) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install @open-pioneer/search
pnpm add @open-pioneer/search
yarn add @open-pioneer/search
bun add @open-pioneer/search
```

## Health

**Score 65/100 (B)** — status: active.

Positive: esm support; no vulnerabilities; has provenance; recently updated; high maintenance score.

Warnings: low downloads; no types.

## Facts

| | |
|---|---|
| Version | 1.7.0 |
| Published | 2026-11-19 |
| First published | 2024-01-04 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | none |
| Module format | ESM |
| Dependencies | 11 |
| Unpacked size | 119.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 13 |
| Maintainers | mbeckem_conterra, jessebluemr, antoniave_conterra, open_pioneer |
| Keywords | open-pioneer-trails |

## Links

- npm: https://www.npmjs.com/package/@open-pioneer/search
- Repository: https://github.com/open-pioneer/trails-openlayers-base-packages
- Homepage: https://github.com/open-pioneer
- npm.io page: https://npm.io/package/@open-pioneer/search

## Dependencies (11)

- [ol](https://npm.io/package/ol.md) ^10.11.0
- [react](https://npm.io/package/react.md) ^19.3.1
- [react-icons](https://npm.io/package/react-icons.md) ^5.7.0
- [@chakra-ui/react](https://npm.io/package/@chakra-ui/react.md) ^3.38.0
- [@open-pioneer/map](https://npm.io/package/@open-pioneer/map.md) 1.7.0
- [@open-pioneer/core](https://npm.io/package/@open-pioneer/core.md) ^4.10.0
- [@open-pioneer/runtime](https://npm.io/package/@open-pioneer/runtime.md) ^4.10.0
- [@open-pioneer/reactivity](https://npm.io/package/@open-pioneer/reactivity.md) ^4.10.0
- [@conterra/reactivity-core](https://npm.io/package/@conterra/reactivity-core.md) ^0.8.9
- [@open-pioneer/react-utils](https://npm.io/package/@open-pioneer/react-utils.md) ^4.10.0
- [@open-pioneer/chakra-snippets](https://npm.io/package/@open-pioneer/chakra-snippets.md) ^4.10.0

## Recent versions

- 1.7.0 (latest) — 2026-11-19
- 1.7.0-dev.20261119092321 (dev) — 2026-11-19
- 1.7.0-dev-test-123.20261117141135 (dev-test-123) — 2026-11-17
- 1.7.0-dev.20261110145318 — 2026-11-10
- 1.6.0 — 2026-10-30
- 1.6.0-dev.20261029095559 — 2026-10-29
- 1.5.0 — 2026-09-17
- 1.5.0-dev.20260917081843 — 2026-09-17
- 1.5.0-dev.20260911123645 — 2026-09-11
- 1.5.0-dev.20260910103330 — 2026-09-10
- 1.4.0 — 2026-07-28
- 1.4.0-dev.20260727093741 — 2026-07-27
- 1.4.0-dev.20260625074633 — 2026-06-25
- 1.4.0-dev.20260624132304 — 2026-06-24
- 1.4.0-dev-chakra-336.20260616133316 — 2026-06-16
- … 53 more at https://npm.io/package/@open-pioneer/search/versions

## README

# @open-pioneer/search

This package provides a UI component to perform a search on given search sources.

The search results are presented as a grouped list, one group for each search source.
This list is sorted by the given order of search sources and the order of the search results inside is
defined by the implementation of the search source.

## Usage

To use the search in your app, insert the following snippet (and reference a map) and `sources` (sources to be searched on):

```tsx
<Search
    map={map}
    sources={searchsources}
/> /* instead of passing the map, the `DefaultMapProvider` can alternatively be used */
```

To change the typing delay, add the optional property `searchTypingDelay` (in ms).
The default value is 200ms.

```tsx
<Search map={map} sources={searchsources} searchTypingDelay={500} />
```

To limit the maximum number of search results to be displayed per search source (group), configure the optional property `maxResultsPerGroup`.
The default value is 5.

```tsx
<Search map={map} sources={searchsources} maxResultsPerGroup={10} />
```

To change the placeholder text of the search field, use the optional property `placeholder`:

```tsx
<Search sources={searchsources} placeholder="Search for cities" />
```

### Listening to events and using the search API

To listen to the events `onSelect` and `onClear`, provide optional callback functions to the component.
In case of the `onSelect` event, you can access the selected search result (and its search source)
from the parameter `SearchSelectEvent`.

```tsx
import { Search, SearchClearEvent, SearchSelectEvent } from "@open-pioneer/search";
// ...
<Search
    map={map}
    sources={datasources}
    onSelect={(event: SearchSelectEvent) => {
        // do something
    }}
    onClear={(event: SearchClearEvent) => {
        // do something
    }}
/>;
```

The search API provides methods to:

- clear the search input (`resetInput`)
- set the search input value without opening the suggestion menu (`setInputValue`)
- execute a search and automatically select the first matching result (`searchAndSelect`)

To receive the API, listen to the `onReady` event which provides the `SearchApi` as a parameter once the search component is ready to use:

```tsx
import { Button } from "@chakra-ui/react";
import { Search, SearchApi, SearchClearEvent, SearchReadyEvent } from "@open-pioneer/search";
import { NotificationService, Notifier } from "@open-pioneer/notifier";
import { useRef } from "react";

const searchApiRef = useRef<SearchApi>(undefined);
const sources = [/* your sources */];

// the clear event contains information about the trigger of the clear action (user or API call)
function onSearchCleared(clearEvent: SearchClearEvent) {
    console.log(clearEvent.trigger); // "api-reset" if triggered via API
}

// ...
<Search
    sources={sources}
    onClear={onSearchCleared}
    onReady={(event: SearchReadyEvent) => {
        // get the API object from the ready event and store it somewhere
        searchApiRef.current = event.api;
    }}
    onDisposed={() => {
        searchApiRef.current = undefined;
    }}
/>

<Button
    onClick={() => {
        searchApiRef.current?.resetInput(); // use the API to clear the search input
    }}
>
    reset search input
</Button>
<Button
    onClick={() => {
        searchApiRef.current?.setInputValue("Münster"); // use the API to set the search input value
    }}
>
    set search input
</Button>
<Button
    onClick={() => {
        searchApiRef.current
            ?.searchAndSelect("Düsseldorf")
            .then((selection) => {
                if (!selection) {
                    console.debug("No matching result found.");
                    return;
                }

                const result = selection.result;
                if (!result.geometry) {
                    console.log("Result has no geometry.");
                    return;
                }
                map.highlightAndZoom([result.geometry]);
            })
            .catch((error) => {
                console.error(error);
            });
    }}
>
    set and selected search input
</Button>
```

`searchAndSelect` performs a search using the provided query, updates the search UI with the returned results, and automatically selects the first matching result. The returned promise resolves to the selected `SearchResult` or `undefined` if no matching result is found.

### Positioning the search bar

The search bar is not placed at a certain location by default; it will simply fill its parent.

To achieve a certain position in a parent node, the following snippet might be helpful:

```css
/* top center placement */
.search-top-center-placement {
    position: absolute;
    left: 50%;
    top: 0px;
    transform: translate(-50%, 0px);
    width: 500px;
    z-index: 1;
}
```

```jsx
<Box
    // ...
    className="search-top-center-placement"
>
    <Search /* ... */ />
</Box>
```

### Implementing a search source

To provide search sources that are used by the search component, implement the function `search` for each datasource:

```tsx
import { Search, SearchSource, SearchResult } from "@open-pioneer/search";
import { MAP_ID } from "./MapConfigProviderImpl";

class MySearchSource implements SearchSource {
    // The optional id of this source. It must be unique among the sources used by the same
    // search component and it must not change. If no id is defined, the search component
    // generates one internally.
    id = "my-sample-rest-service";

    // The label of this source, used as a title for this source's results.
    label = "My sample REST-Service";

    // Attempts to retrieve results for the given input string. For more details,
    // see the API documentation of `SearchSource`.
    async search(inputValue: string, options: SearchOptions): Promise<SearchResult[]> {
        // implement
    }
}

const searchsources: SearchSource[] = [new MySearchSource()];

// In your JSX template:
<Search map={map} sources={searchsources} />;
```

The configured maximum number of `maxResultsPerGroup` is passed as `maxResults` inside the option parameter
of the search function, so you are able to fetch no more results than necessary.

## License

Apache-2.0 (see `LICENSE` file)

---
_Source: https://npm.io/package/@open-pioneer/search · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
