> ## 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 = () =>
search query
;
export const FlavorSwitcher = ({current, baseHref = "", options = [], label = "InstantSearch framework"}) => {
if (options.length === 0) {
return
FlavorSwitcher requires at least one option.
;
}
const selected = options.find(option => option.value === current) ?? options[0];
return ;
};
```kotlin Signature theme={"system"}
SearchBoxConnector(
searcher: Searcher
viewModel: SearchBoxViewModel
searchMode: SearchMode
debouncer: Debouncer
searchOnQueryUpdate: Boolean
)
```
Browse the SearchBox example code on GitHub.
## About this widget
The `SearchBox` is used to perform a text-based .
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
The [`Searcher`](/doc/api-reference/widgets/instantsearch/android) that handles your searches.
The business logic that handles new search inputs.
Defines the event triggering a new search.
* `SearchMode.AsYouType`. Triggers a search on each keystroke.
* `SearchMode.OnSubmit`. Triggers a search on submitting the query.
Delays searcher operations by a specified time duration.
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.
## View
The view that handles the input.
```kotlin Kotlin icon=code theme={"system"}
val searchView = SearchView(this)
val view: SearchBoxView = SearchBoxViewAppCompat(searchView)
searchBox.connectView(view)
```
### 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()
}
}
```