> ## 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.

If none of the existing widgets fit your use case, you can implement your own.

<Info>
  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.
</Info>

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.

<Steps>
  <Step title="Create the view model">
    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
        }
    }
    ```
  </Step>

  <Step title="Create the view interface">
    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<Unit>? // will hold the callback to reset the sum
    }
    ```
  </Step>

  <Step title="Implement the view">
    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<Unit>? = null
    }
    ```
  </Step>

  <Step title="Create the connection view">
    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
        }
    }
    ```
  </Step>

  <Step title="Create the connection searcher">
    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)
        }
    }
    ```
  </Step>

  <Step title="Create helper functions">
    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)
    }
    ```
  </Step>
</Steps>

## 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()
```