> ## Documentation Index
> Fetch the complete documentation index at: https://algolia.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Create your own InstantSearch Android widgets
> Learn how you can create a custom widget for your InstantSearch Android app.
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 ;
};
If none of the existing widgets fit your use case, you can implement your own.
If you're creating a custom InstantSearch widget because you didn't find a built-in option for your use case,
consider [opening a feature request](https://github.com/algolia/instantsearch/discussions/new?category=ideas\&labels=triage\&title=Feature%20request%3A%20) to describe what you're trying to build.
Creating a widget takes three steps:
* Create the `MyWidgetViewModel`, containing the business logic for your widget.
* Create a `MyWidgetView` interface, describing the rendering of the widget data.
* Implement your view in a `MyWidgetViewImpl` that you'll use.
* Create the `Connection`s between your `ViewModel` and the other components:
* Create a `MyWidgetConnectionView` to connect your `ViewModel` to its `View`.
* If it uses the `Searcher`, create a `MyWidgetConnectionSearcher`.
* If it uses the `FilterState`, create a `MyWidgetConnectionFilterState`.
## Example
You'll build a widget that displays the number of searches made since it was last clicked.
The `ViewModel` will be quite straightforward: it stores a `sum` that can be `increment`ed or `reset`ed to 0.
It will use InstantSearch's `SubscriptionValue` to allow subscribing to changes of the `sum`'s value.
```kotlin Kotlin theme={"system"}
class SumSearchesViewModel {
val sum = SubscriptionValue(0)
fun increment() {
sum.value++
}
fun reset() {
sum.value = 0
}
}
```
To interact with the data in our `ViewModel`, you need a view than can display a number, and handle clicks for resetting.
```kotlin Kotlin theme={"system"}
interface SumSearchesView {
fun setSum(sum: Int) // will be called on new sum
var onReset: Callback? // will hold the callback to reset the sum
}
```
Implement a `SumSearchesView`:
it should display the data received in `setSum` and trigger the `onReset` when clicked.
```kotlin Kotlin theme={"system"}
class SumSearchesViewImpl(val view: TextView) : SumSearchesView {
init {
view.setOnClickListener { onReset?.invoke(Unit) }
}
override fun setSum(sum: Int) {
view.text = "$sum searches."
}
override var onReset: Callback? = null
}
```
To link the `ViewModel` and its `View`,
define a connection to describe what should happen when connecting (subscribe to `sum` and set the reset callback) and when disconnecting (unsubscribe to `sum` and remove the callback).
```kotlin Kotlin theme={"system"}
data class SumSearchesConnectionView(
private val viewModel: SumSearchesViewModel,
private val view: SumSearchesView
) : ConnectionImpl() {
private val updateViewSum: (Int) -> Unit = {
view.setSum(it)
}
override fun connect() {
super.connect()
viewModel.sum.subscribePast(updateViewSum)
view.onReset = { viewModel.reset() }
}
override fun disconnect() {
super.disconnect()
viewModel.sum.unsubscribe(updateViewSum)
view.onReset = null
}
}
```
Because the widget needs to be aware of searches to count them,
it needs to be connected to a [`Searcher`](/doc/api-reference/widgets/instantsearch/android).
Subscribe to its `response` to call `increment()` on every new search response.
```kotlin Kotlin theme={"system"}
import com.algolia.client.model.search.SearchResponse
data class SumSearchesConnectionSearcher(
private val viewModel: SumSearchesViewModel,
private val searcher: HitsSearcher
) : ConnectionImpl() {
private val updateSum: (SearchResponse?) -> Unit = {
viewModel.increment()
}
override fun connect() {
super.connect()
searcher.response.subscribe(updateSum)
}
override fun disconnect() {
super.disconnect()
searcher.response.unsubscribe(updateSum)
}
}
```
To simplify usage of the widget,
create two extension functions that connect the `ViewModel` to other components:
```kotlin Kotlin theme={"system"}
fun SumSearchesViewModel.connectView(
view: SumSearchesView
): Connection {
return SumSearchesConnectionView(this, view)
}
fun SumSearchesViewModel.connectSearcher(
searcher: HitsSearcher
): Connection {
return SumSearchesConnectionSearcher(this, searcher)
}
```
## Final touches
You just created your first custom widget and you can now use it in your app like any other widget:
```kotlin Kotlin theme={"system"}
val searcher = HitsSearcher(
applicationID = "YourApplicationID",
apiKey = "YourSearchOnlyAPIKey",
indexName = "YourIndexName"
) // Initialize your Searcher
val view = TextView(context) // Create or find the view you want to use
// Create a connectionHandler to hold all connections
val connection = ConnectionHandler()
// Create your ViewModel and View implementation
val viewModel = SumSearchesViewModel()
val sumView = SumSearchesViewImpl(view)
// Connect your ViewModel to start displaying the count of searches
connection += viewModel.connectSearcher(searcher)
connection += viewModel.connectView(sumView)
// When you want to disconnect everything and ensure no memory leak
// for example in your Activity's onDestroy()`
connection.disconnect()
```