SearchBox

Lets users perform a search using text input.

Signature

  SearchBoxConnector(
      searcher: Searcher
      viewModel: SearchBoxViewModel
      searchMode: SearchMode
      debouncer: Debouncer
      searchOnQueryUpdate: Boolean
  )

Explore example code

About this widget

The SearchBox is used to perform a text-based query.

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

• Searcher. The Searcher 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

Examples

Kotlin

class MyActivity : AppCompatActivity() {
    val searcher = HitsSearcher(
        applicationID = ApplicationID("YourApplicationID"),
        apiKey = APIKey("YourSearchOnlyAPIKey"),
        indexName = 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

searcher · Searcher · required

The Searcher that handles your searches.

viewModel · SearchBoxViewModel · default: SearchBoxViewModel()

The business logic that handles new search inputs.

searchMode · SearchMode · 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.

debouncer · Debouncer · default: Debouncer(debounceLoadingInMillis)

Delays searcher operations by a specified time duration.

searchOnQueryUpdate · Boolean · default: true

Controls whether the Searcher 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

searchBoxView · SearchBoxView · required

The view that handles the input.

Kotlin

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

class MyActivity : AppCompatActivity() {
    val searcher = HitsSearcher(
        applicationID = ApplicationID("YourApplicationID"),
        apiKey = APIKey("YourSearchOnlyAPIKey"),
        indexName = 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()
    }
}