> For the complete documentation index, see [llms.txt](https://docs.apryse.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.apryse.com/web/search/advance-text-search.md).

# Alternate PDF UI Search Capabilities

Enhance text search capabilities in the UI with WebViewer's programmatic features. Explore methods like textSearchInit, clearSearchResults, and more for precise control over UI search results using we

WebViewer UI has a built-in search panel and provides an API for controlling the search UI. [Launch Demo to see WebViewer search](https://showcase.apryse.com/pdf-search). The following functions can be used to interact with the text search:

* [`addSearchListener`](https://sdk.apryse.com/api/web/UI.html#.addSearchListener): Adds a function that is called whenever there is a match or when finishing a full search.
* [`removeSearchListener`](https://sdk.apryse.com/api/web/UI.html#.removeSearchListener): Removes a search callback function.
* [`searchText`](https://sdk.apryse.com/api/web/UI.html#.searchText): Searches and highlights the first instance of a search term. Can be called more than once to search for the next instance.
* [`searchTextFull`](https://sdk.apryse.com/api/web/UI.html#.searchTextFull): Searches for all instances of a search term. This also displays the search sidebar shown in the image below.

![](https://3532544125-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FX9YnTSKIHvV7m0A36LbO%2Fuploads%2Fgit-blob-4b47a8a868495553eb7ff9cbe5a5f6a13041df9c%2Fca90402dd687976dd7e1b7c9253a71ac94cdee85-855x429.png?alt=media)

The following is an example of `searchTextFull` being used to search text and adding a [`searchListener`](https://sdk.apryse.com/api/web/UI.html#.searchListener) callback to create annotations on top of the results.

{% tabs %}
{% tab title="JavaScript" %}
{% code lineNumbers="true" %}

```js
WebViewer({ ... }, viewerElement).then(instance => {
  const { annotationManager, documentViewer, Annotations } = instance.Core;

  const searchListener = (searchPattern, options, results) => {
    // add redaction annotation for each search result
    const newAnnotations = results.map(result => {
      const annotation = new Annotations.RedactionAnnotation();
      annotation.PageNumber = result.pageNum;
      annotation.Quads = result.quads.map(quad => quad.getPoints());
      annotation.StrokeColor = new Annotations.Color(136, 39, 31);
      return annotation;
    });

    annotationManager.addAnnotations(newAnnotations);
    annotationManager.drawAnnotationsFromList(newAnnotations);
  };

  documentViewer.addEventListener('documentLoaded', () => {
    const searchPattern = 'text to search';
    // searchPattern can be something like "search*m" with "wildcard" option set to true
    // searchPattern can be something like "search1|search2" with "regex" option set to true

    // options default values are false
    const searchOptions = {
      caseSensitive: true,  // match case
      wholeWord: true,      // match whole words only
      wildcard: false,      // allow using '*' as a wildcard value
      regex: false,         // string is treated as a regular expression
      searchUp: false,      // search from the end of the document upwards
      ambientString: true,  // return ambient string as part of the result
    };

    instance.UI.addSearchListener(searchListener);
    // start search after document loads
    instance.UI.searchTextFull(searchPattern, searchOptions);
  });
});
```

{% endcode %}
{% endtab %}
{% endtabs %}

[AnnotationManager.addAnnotations](https://sdk.apryse.com/api/web/Core.AnnotationManager.html#addAnnotations__anchor) [AnnotationManager.drawAnnotationsFromList](https://sdk.apryse.com/api/web/Core.AnnotationManager.html#drawAnnotationsFromList__anchor)

After the document has been loaded, a [`searchListener`](https://sdk.apryse.com/api/web/UI.html#.searchListener) callback function is added and `searchTextFull` is used to search the document. When calling `searchTextFull`, the `searchListener` callback is invoked once and receives an array of all the results (even if nothing was found). When using the `searchText` method, the `searchListener` callback will only be invoked if a result was found.

When the `searchListener` callback function is called, it'll receive the `searchPattern` and `options` used for the search and an array containing [`SearchResults`](https://sdk.apryse.com/api/web/Core.DocumentViewer.html#.SearchResults__anchor) objects. In the example above, it creates redaction annotations on top of the matching text to illustrate how `SearchResults` objects can be used.

## TextSearchInit

Besides the [basic text search functions from WebViewer UI](/web/search/text-search.md), WebViewer provides methods for more low level control of text search. They are:

* [`textSearchInit`](https://sdk.apryse.com/api/web/Core.DocumentViewer.html#textSearchInit__anchor): Starts a search or search for the next occurrence of a search term.
* [`clearSearchResults`](https://sdk.apryse.com/api/web/Core.DocumentViewer.html#clearSearchResults__anchor): Clears highlighted search results.
* [`displaySearchResult`](https://sdk.apryse.com/api/web/Core.DocumentViewer.html#displaySearchResult__anchor): Highlights result, unhighlights previous result.
* [`displayAdditionalSearchResult`](https://sdk.apryse.com/api/web/Core.DocumentViewer.html#displayAdditionalSearchResult__anchor): Highlights additional result.
* [`setActiveSearchResult`](https://sdk.apryse.com/api/web/Core.DocumentViewer.html#setActiveSearchResult__anchor): Goes to search result and highlights it with 'active' color.
* [`setSearchHighlightColors`](https://sdk.apryse.com/api/web/Core.DocumentViewer.html#setSearchHighlightColors__anchor): Sets highlight colors of search results.
* [`searchInProgress`](https://sdk.apryse.com/api/web/Core.DocumentViewer.html#searchInProgress__anchor): Fires event when a search starts or ends.

The `textSearchInit` function is used to start a text search and the `displaySearchResult`, `displayAdditionalSearchResult`, and `setActiveSearchResult` functions are used to highlight the results.

The following is an example of `textSearchInit` being used:

{% tabs %}
{% tab title="JavaScript" %}
{% code lineNumbers="true" %}

```js
WebViewer({ ... }, viewerElement).then(instance => {
  const { documentViewer, Annotations, Search } = instance.Core;
  documentViewer.setSearchHighlightColors({
    // setSearchHighlightColors accepts both Annotations.Color objects or 'rgba' strings.
    searchResult: new Annotations.Color(0, 0, 255, 0.5),
    activeSearchResult: 'rgba(0, 255, 0, 0.5)'
  });
  documentViewer.addEventListener('documentLoaded', () => {
    const searchText = 'TEXT TO SEARCH';
    const mode = [Search.Mode.PAGE_STOP, Search.Mode.HIGHLIGHT];
    const searchOptions = {
      // If true, a search of the entire document will be performed. Otherwise, a single search will be performed.
      fullSearch: true,
      // The callback function that is called when the search returns a result.
      onResult: result => {
        // with 'PAGE_STOP' mode, the callback is invoked after each page has been searched.
        if (result.resultCode === Search.ResultCode.FOUND) {
          const textQuad = result.quads[0].getPoints(); // getPoints will return Quad objects
          // Now that we have the result Quads, it's possible to highlight text or create annotations on top of the text.
        }
      }
    };
    documentViewer.textSearchInit(searchText, mode, searchOptions);
  });
});
```

{% endcode %}
{% endtab %}
{% endtabs %}

[DocumentViewer.setSearchHighlightColors](https://sdk.apryse.com/api/web/Core.DocumentViewer.html#setSearchHighlightColors__anchor) [DocumentViewer.textSearchInit](https://sdk.apryse.com/api/web/Core.DocumentViewer.html#textSearchInit__anchor)

In the code above, the `textSearchInit` method is used to search the document. It takes the following input parameters:

* `searchPattern`: A pattern to search for.
* `mode`: A number that encodes the search options, generated by bitwise ORing options together.
* `searchOptions`: An object that contains the search options.
* `searchCallBack`: A callback function that gets called when a match has been found or at the end of document (or when using `PAGE_STOP`, at the end of a page).

The 'mode' value it takes in can be created by completing bitwise OR operations on the different [`SearchMode`](https://sdk.apryse.com/api/web/Core.Search.html) properties. The search modes are:

* `CASE_SENSITIVE`: Text must match the case of the search term.
* `SEARCH_UP`: Search starts on the last page, and searches backwards to the first page.
* `PAGE_STOP`: Search invokes the callback function when it finishes searching a page.
* `HIGHLIGHT`: Bounding box of found term will be included.
* `AMBIENT_STRING`: Characters surrounding the search term will be included.
* `WHOLE_WORD`: Text must be a whole word.
* `REGEX`: Search text can contain regular expressions.
* `WILD_CARD`: Search text can contain wildcards.

When the callback function is called, it receives a [`SearchResults`](https://sdk.apryse.com/api/web/Core.Search.html) object that has a few useful properties. It has a `resultCode` property, which has one of the following values:

* `ResultCode.PAGE`: Reached the end of a page.
* `ResultCode.FOUND`: Found a match.
* `ResultCode.DONE`: Done searching the document.

The `searchResults` will also have a `quads` property that contains an array of `textQuad` objects. You can call the `getPoints` function on `textQuad` objects to receive a `Quad` object.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.apryse.com/web/search/advance-text-search.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.