> ## Documentation Index
> Fetch the complete documentation index at: https://algolia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SearchBox

> Lets users perform a search using text input.

export const SearchQuery = () => <Tooltip tip="The text users enter into a search box. In the Search API, this corresponds to the query parameter. A search query is often used with filters, facets, and other parameters, but these aren't part of the query text itself.">
    search query
  </Tooltip>;

```kotlin Signature theme={"system"}
  SearchBoxConnector(
      searcher: Searcher
      viewModel: SearchBoxViewModel
      searchMode: SearchMode
      debouncer: Debouncer
      searchOnQueryUpdate: Boolean
  )
```

<Card title="Explore example code" icon="github" href="https://github.com/algolia/instantsearch-android/blob/master/examples/android/src/main/kotlin/com/algolia/instantsearch/examples/android/showcase/androidview/search/SearchAsYouTypeShowcase.kt">
  Browse the SearchBox example code on GitHub.
</Card>

## About this widget

The `SearchBox` is used to perform a text-based <SearchQuery />.

To add a `SearchBox` to your search experience, use these components:

* `Searcher`. The [`Searcher`](/doc/api-reference/widgets/instantsearch/android) that handles your searches.
* `SearchBoxViewModel`. The business logic that handles new search inputs.
* `SearchBoxView`. The view that handles the input.

See also: [Getting started with imperative UI](/doc/guides/building-search-ui/getting-started/how-to/programmatically/android)

## Examples

```kotlin Kotlin icon=code theme={"system"}
class MyActivity : AppCompatActivity() {
    val searcher = HitsSearcher(
        applicationID = "YourApplicationID",
        apiKey = "YourSearchOnlyAPIKey",
        indexName = "YourIndexName"
    )
    val searchBox = SearchBoxConnector(searcher)
    val connection = ConnectionHandler(searchBox)

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        val searchView = SearchView(this)
        val view: SearchBoxView = SearchBoxViewAppCompat(searchView)
        connection += searchBox.connectView(view)
        searcher.searchAsync()
    }

    override fun onDestroy() {
        super.onDestroy()
        connection.disconnect()
        searcher.cancel()
    }
}
```

## Parameters

<ParamField body="searcher" type="Searcher" required>
  The [`Searcher`](/doc/api-reference/widgets/instantsearch/android) that handles your searches.
</ParamField>

<ParamField body="viewModel" type="SearchBoxViewModel" post={["default: SearchBoxViewModel()"]}>
  The business logic that handles new search inputs.
</ParamField>

<ParamField body="searchMode" type="SearchMode" post={["default: SearchMode.AsYouType"]}>
  Defines the event triggering a new search.

  * `SearchMode.AsYouType`. Triggers a search on each keystroke.
  * `SearchMode.OnSubmit`. Triggers a search on submitting the query.
</ParamField>

<ParamField body="debouncer" type="Debouncer" post={["default: Debouncer(debounceLoadingInMillis)"]}>
  Delays searcher operations by a specified time duration.
</ParamField>

<ParamField body="searchOnQueryUpdate" type="Boolean" post={["default: true"]}>
  Controls whether the [`Searcher`](/doc/api-reference/widgets/instantsearch/android) automatically runs a search when the query changes. When `true` (default), typing or submitting updates the query and triggers a search. When `false`, the query updates but no search is sent until you trigger it manually, giving you full control over when searches occur.
</ParamField>

## View

<ParamField body="searchBoxView" type="SearchBoxView" required>
  The view that handles the input.

  ```kotlin Kotlin icon=code theme={"system"}
  val searchView = SearchView(this)
  val view: SearchBoxView = SearchBoxViewAppCompat(searchView)
  searchBox.connectView(view)
  ```
</ParamField>

### Compose UI

InstantSearch provides `SearchBoxState` as a state model, which is an implementation of the `SearchBoxView` interface.
You need to connect `SearchBoxState` to the `SearchBoxConnector` or `SearchBoxViewModel` like any other `SearchBoxView` implementation,
and create a Compose UI view that handles the query input, you can directly use the `SearchBoxState` as a state model,
It provides the `query` property along with the `setText` function to streamline the design process of your custom Compose UI view.

```kotlin Kotlin icon=code theme={"system"}
class MyActivity : AppCompatActivity() {
    val searcher = HitsSearcher(
        applicationID = "YourApplicationID",
        apiKey = "YourSearchOnlyAPIKey",
        indexName = "YourIndexName"
    )
    val searchBoxState = SearchBoxState()
    val searchBox = SearchBoxConnector(searcher)
    val connections = ConnectionHandler(searchBox)

    init {
        connections += searchBox.connectView(searchBoxState)
    }

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContent {
            TextField(
                // set query as text value
                value = searchBoxState.query,
                // update text on value change
                onValueChange = { searchBoxState.setText(it) },
                // set ime action to "search"
                keyboardOptions = KeyboardOptions(imeAction = ImeAction.Search),
                // set text as query submit on search action
                keyboardActions = KeyboardActions(
                    onSearch = { searchBoxState.setText(searchBoxState.query, true)}
                )
            )
        }
        searcher.searchAsync()
    }

    override fun onDestroy() {
        super.onDestroy()
        connections.disconnect()
        searcher.cancel()
    }
}
```