> For the complete documentation index, see [llms.txt](https://docs.mapbox.com/android/search/llms.txt)

# Search results view

[`SearchResultsView`](https://docs.mapbox.com/android/search/api/ui/2.28.2/ui/com.mapbox.search.ui.view/-search-results-view/) - is a UI component that can display search results list. Technically, this is a subclass of the [`RecyclerView`](https://developer.android.com/reference/androidx/recyclerview/widget/RecyclerView) with predefined [Adapter](https://developer.android.com/reference/androidx/recyclerview/widget/RecyclerView.Adapter) where items represent search states, for example, search result items that display details like name, address, distance to the place from user's location, and icon.

Your browser doesn't support HTML5 video. Open [link to the video](https://docs.mapbox.com/android/android/assets/medias/search-results-view-demo-32e073fc4b69b4f5202a588c6de7ef46.mp4).

## Integration

**`SearchResultsView`** inherits all the functionality from Android SDK [`RecyclerView`](https://developer.android.com/reference/androidx/recyclerview/widget/RecyclerView), it can be added to your layout the way you would add any other UI element:

```xml
<com.mapbox.search.ui.view.SearchResultsView
    android:id="@+id/search_results_view"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:background="@drawable/card_background"
    android:clipToPadding="false"
    android:elevation="4dp"
    android:paddingTop="8dp"
    android:paddingBottom="22dp"
/>
```

```kotlin
val searchResultsView = findViewById<SearchResultsView>(R.id.search_results_view)
```

To make `SearchResultsView` work properly, you will have to call [initialize()](https://docs.mapbox.com/android/search/api/ui/2.28.2/ui/com.mapbox.search.ui.view/-search-results-view/initialize.html) function where you will need to pass [CommonSearchViewConfiguration](https://docs.mapbox.com/android/search/api/ui/2.28.2/ui/com.mapbox.search.ui.view/-common-search-view-configuration/) object with [DistanceUnitType](https://docs.mapbox.com/android/search/api/ui/2.28.2/ui/com.mapbox.search.ui.view/-distance-unit-type/), which tells the view how to display distances, in meters or miles:

```kotlin
searchResultsView.initialize(
    SearchResultsView.Configuration(
        CommonSearchViewConfiguration(DistanceUnitType.IMPERIAL)
    )
)
```

To fill the view with the items, you will need to call [setAdapterItems()](https://docs.mapbox.com/android/search/api/ui/2.28.2/ui/com.mapbox.search.ui.view/-search-results-view/set-adapter-items.html) function where you will need to provider the list of [SearchResultAdapterItem](https://docs.mapbox.com/android/search/api/ui/2.28.2/ui/com.mapbox.search.ui.view/-search-result-adapter-item/). `SearchResultAdapterItem` is an abstract class which provides a list of predefined subtypes that can be used as adapter items. The subtypes are:

-   [SearchResultAdapterItem.Loading](https://docs.mapbox.com/android/search/api/ui/2.28.2/ui/com.mapbox.search.ui.view/-search-result-adapter-item/-loading/)
-   [SearchResultAdapterItem.RecentSearchesHeader](https://docs.mapbox.com/android/search/api/ui/2.28.2/ui/com.mapbox.search.ui.view/-search-result-adapter-item/-recent-searches-header/)
-   [SearchResultAdapterItem.EmptyHistory](https://docs.mapbox.com/android/search/api/ui/2.28.2/ui/com.mapbox.search.ui.view/-search-result-adapter-item/-empty-history/)
-   [SearchResultAdapterItem.History](https://docs.mapbox.com/android/search/api/ui/2.28.2/ui/com.mapbox.search.ui.view/-search-result-adapter-item/-history/)
-   [SearchResultAdapterItem.EmptySearchResults](https://docs.mapbox.com/android/search/api/ui/2.28.2/ui/com.mapbox.search.ui.view/-search-result-adapter-item/-empty-search-results/)
-   [SearchResultAdapterItem.Result](https://docs.mapbox.com/android/search/api/ui/2.28.2/ui/com.mapbox.search.ui.view/-search-result-adapter-item/-result/)
-   [SearchResultAdapterItem.MissingResultFeedback](https://docs.mapbox.com/android/search/api/ui/2.28.2/ui/com.mapbox.search.ui.view/-search-result-adapter-item/-missing-result-feedback/)
-   [SearchResultAdapterItem.Error](https://docs.mapbox.com/android/search/api/ui/2.28.2/ui/com.mapbox.search.ui.view/-search-result-adapter-item/-error/)

These types should be combined together in the way that represent one of possible search states. Let's look at the code example. The following code snippet shows user's [search history](https://docs.mapbox.com/android/search/guides/search-engine/search-history/) on the `SearchResultsView`:

1.  Initially we show `SearchResultAdapterItem.Loading` item that indicates the progress of `search history` loading operation
2.  Load `search history items`
3.  If the loading operation completed successfully, we show loading items and `Recent searches` header
4.  If the loading operation failed, we show error

```kotlin
fun showSearchHistory() {
    val historyDataProvider = ServiceProvider.INSTANCE.historyDataProvider()
    
    // Show `loading` item that indicates the progress of `search history` loading operation.
    searchResultsView.setAdapterItems(listOf(SearchResultAdapterItem.Loading))
    
    // Load `search history`
    loadingTask = historyDataProvider.getAll(object : CompletionCallback<List<HistoryRecord>> {
        override fun onComplete(result: List<HistoryRecord>) {
            val viewItems = mutableListOf<SearchResultAdapterItem>().apply {
                // Add `Recent searches` header
                add(SearchResultAdapterItem.RecentSearchesHeader)
                
                // Add history record items
                addAll(result.map { history ->
                    SearchResultAdapterItem.History(
                        history,
                        isFavorite = false
                    )
                })
            }

            // Show prepared items
            searchResultsView.setAdapterItems(viewItems)
        }

        override fun onError(e: Exception) {
            // Show error in case of failure
            val errorItem = SearchResultAdapterItem.Error(UiError.createFromException(e))
            searchResultsView.setAdapterItems(listOf(errorItem))
        }
    })
}
```

Each [setAdapterItems()](https://docs.mapbox.com/android/search/api/ui/2.28.2/ui/com.mapbox.search.ui.view/-search-results-view/set-adapter-items.html) call replaces previous added items, so we don't need to explicitly remove `loading` item when we want to show `search history` elements.

## Adapters

**`SearchResultsView`** is a flexible view which is not tied to concrete SDK. For example, you can use it to show search results from any source like [Search Engine](https://docs.mapbox.com/android/search/guides/search-engine/), [Offline Search Engine](https://docs.mapbox.com/android/search/guides/search-engine/offline/), [Address Autofill](https://docs.mapbox.com/android/search/guides/address-autofill/), etc.

[Search UI](https://docs.mapbox.com/android/search/guides/search-ui/) provides ready-made adapters for the **`SearchResultsView`** that implement interactions with the core parts of SDK and provide simplified interface for users.

### `SearchEngineUiAdapter`

[`SearchEngineUiAdapter`](https://docs.mapbox.com/android/search/api/ui/2.28.2/ui/com.mapbox.search.ui.adapter.engines/-search-engine-ui-adapter/) is an adapter for the [Search Engine](https://docs.mapbox.com/android/search/guides/search-engine/) and [Offline Search Engine](https://docs.mapbox.com/android/search/guides/search-engine/offline/). `SearchEngineUiAdapter` implements logic that:

-   Shows search history when search query is empty
-   Shows search suggestions when a user types search query
-   Switches between online and offline search engines depending on device's connectivity

Your browser doesn't support HTML5 video. Open [link to the video](https://docs.mapbox.com/android/android/assets/medias/search-online-offline-maps-demo-8bfecab58618d8abd9ae96f73d3eed8f.mp4).

To integrate `SearchEngineUiAdapter` into your app, you will need to complete the following steps:

1.  Instantiate the [`SearchEngineUiAdapter`](https://docs.mapbox.com/android/search/api/ui/2.28.2/ui/com.mapbox.search.ui.adapter.engines/-search-engine-ui-adapter/-search-engine-ui-adapter.html)

```kotlin
val searchResultsView = findViewById<SearchResultsView>(R.id.search_results_view)
// searchResultsView initialization

val searchEngine = SearchEngine.createSearchEngineWithBuiltInDataProviders(
    SearchEngineSettings(getString(R.string.mapbox_access_token))
)

val offlineSearchEngine = OfflineSearchEngine.create(
    OfflineSearchEngineSettings(getString(R.string.mapbox_access_token))
)

val searchEngineUiAdapter = SearchEngineUiAdapter(
    view = searchResultsView,
    searchEngine = searchEngine,
    offlineSearchEngine = offlineSearchEngine,
)
```

2.  Add [SearchEngineUiAdapter.SearchListener](https://docs.mapbox.com/android/search/api/ui/2.28.2/ui/com.mapbox.search.ui.adapter.engines/-search-engine-ui-adapter/-search-listener/) to process user clicks and search events

```kotlin
searchEngineUiAdapter.addSearchListener(object : SearchEngineUiAdapter.SearchListener {
    // interface implementation
})
```

3.  Call [search()](https://docs.mapbox.com/android/search/api/ui/2.28.2/ui/com.mapbox.search.ui.adapter.engines/-search-engine-ui-adapter/search.html) function when the query text is changed by the user

```kotlin
fun onQueryTextChange(newText: String) {
    searchEngineUiAdapter.search(newText)
}
```

That's it! These steps are enough to add search experience to your app. Explore all the `SearchEngineUiAdapter`'s functionality in the [SearchEngineUiAdapter API reference page](https://docs.mapbox.com/android/search/api/ui/2.28.2/ui/com.mapbox.search.ui.adapter.engines/-search-engine-ui-adapter/).

Below you can find a complete sample that shows integration of the `SearchEngineUiAdapter` with `Place card` and Maps SDK.

> **Related content (example): [Search Engine example](https://docs.mapbox.com/android/search/examples/maps-sdk-integration/)**
> 
> Search Engine example that utilizes the `SearchResultsView` UI component with `SearchEngineUiAdapter`.

### `AddressAutofillUiAdapter`

[`AddressAutofillUiAdapter`](https://docs.mapbox.com/android/search/api/ui/2.28.2/ui/com.mapbox.search.ui.adapter.autofill/-address-autofill-ui-adapter/) is an adapter for the [Address Autofill SDK](https://docs.mapbox.com/android/search/guides/search-ui/).

Your browser doesn't support HTML5 video. Open [link to the video](https://docs.mapbox.com/android/android/assets/medias/search-autofill-demo-257a6197a64ee4750643d7a1f14cb429.mp4).

This integration is like the `SearchEngineUiAdapter` integration.

1.  Instantiate the [`AddressAutofillUiAdapter`](https://docs.mapbox.com/android/search/api/ui/2.28.2/ui/com.mapbox.search.ui.adapter.autofill/-address-autofill-ui-adapter/-address-autofill-ui-adapter.html)

```kotlin
val searchResultsView = findViewById<SearchResultsView>(R.id.search_results_view)
// searchResultsView initialization

val addressAutofill = AddressAutofill.create(getString(R.string.mapbox_access_token))

val addressAutofillUiAdapter = AddressAutofillUiAdapter(
    view = searchResultsView,
    addressAutofill = addressAutofill
)
```

2.  Add [AddressAutofillUiAdapter.SearchListener](https://docs.mapbox.com/android/search/api/ui/2.28.2/ui/com.mapbox.search.ui.adapter.autofill/-address-autofill-ui-adapter/-search-listener/) to process user clicks and autofill events

```kotlin
addressAutofillUiAdapter.addSearchListener(object : AddressAutofillUiAdapter.SearchListener {
    // interface implementation
})
```

3.  Call [search()](https://docs.mapbox.com/android/search/api/ui/2.28.2/ui/com.mapbox.search.ui.adapter.engines/-search-engine-ui-adapter/search.html) function when the query text is changed by the user. `search()` is a suspend function which [should be called only from a coroutine or another suspend function](https://developer.android.com/topic/libraries/architecture/coroutines). In this short example we will assume that we call it from Activity's `lifecycleScope`:

```kotlin
fun onQueryTextChange(newText: String) {
    val query = Query.create(newText)
    if (query != null) {
        lifecycleScope.launchWhenStarted {
            addressAutofillUiAdapter.search(query)
        }
    }
}
```

That's it? Explore all the `AddressAutofillUiAdapter`'s functionality in the [AddressAutofillUiAdapter API reference page](https://docs.mapbox.com/android/search/api/ui/2.28.2/ui/com.mapbox.search.ui.adapter.autofill/-address-autofill-ui-adapter/).

Below you can find a complete sample that shows integration of the `AddressAutofillUiAdapter`.

> **Related content (example): [Address Autofill example](https://docs.mapbox.com/android/search/examples/autofill-ui/)**
> 
> Search Engine example that utilizes the SearchResultsView UI component with `AddressAutofillUiAdapter`.

---