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

> Learn how you can create a custom widget for your InstantSearch iOS app.

<Info>
  Starting May 1, 2024,
  Apple requires all iOS apps to include a privacy manifest.
  For more information, see [Privacy manifest](/doc/guides/building-search-ui/resources/privacy-manifest/ios/).
</Info>

If none of the existing widgets fit your use-case, you could implement your own widget.

<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 `MyWidgetInteractor`, containing the business logic for your widget.

* Create a `MyWidgetController` interface, describing the rendering of the widget data.

  * Implement it in a `MyConcreteWidgetController` that you will use.

* Create the connection methods between your `Interactor` and every other component:

  * Create a `connectController()` to connect your `Interactor` to its `Controller`.
  * If it uses the `Searcher`, a `connectSearcher()`.
  * If it uses the `FilterState`, a `connectFilterState()`.

## Example

You will build a widget that displays the number of searches made since it was last clicked.

<Steps>
  <Step title="Create the interactor">
    The `Interactor` stores a `sum` that can be incremented or reset to 0.
    You can use InstantSearch's `Observer` to allow subscribing to changes of the sum's value.

    ```swift Swift icon=code theme={"system"}
    class SumSearchesInteractor {

      var sum: Int = 0 {
        didSet {
          onSumChanged.fire(sum)
        }
      }

      public let onSumChanged: Observer<Int> = .init()

      func increment() {
        sum += 1
      }

      func reset() {
        sum = 0
      }

    }
    ```
  </Step>

  <Step title="Create the controller interface">
    To interact with the data in the `ViewModel`,
    you need a view than can display a number, and handle clicks to reset the counter.

    ```swift Swift icon=code theme={"system"}
    protocol SumSearchesController {
        func setSum(sum: Int) // will be called on new sum
        var onReset: (() -> Void)? { get set } // will hold the callback to reset the sum
    }
    ```
  </Step>

  <Step title="Implement the controller">
    The `SumSearchesButtonController` should display the data received in `setSum` and trigger `onReset` when clicked.

    ```swift Swift icon=code theme={"system"}
    class SumSearchesButtonController : SumSearchesController {

      let button: UIButton
      var onReset: (() -> Void)?

      init(button: UIButton) {
        self.button = button
        button.addTarget(self, action: #selector(didPressButton), for: .touchUpInside)
      }

      func setSum(sum: Int) {
        button.setTitle("\(sum)", for: .normal)
      }

      @objc func didPressButton() {
        onReset?()
      }

    }
    ```
  </Step>

  <Step title="Create the connect controller method">
    To link the `Interactor` with its `Controller`,
    define a connection method to describe what should happen when connecting them
    (subscribe to `sum` and set the reset callback).

    You can do this in the `Interactor` extension.

    ```swift Swift icon=code theme={"system"}
    extension SumSearchesInteractor {

      func connectController<Controller: SumSearchesController>(_ controller: Controller) {
        onSumChanged.subscribePast(with: self) { (interactor, sum) in
          controller.setSum(sum: sum)
        }

        controller.onReset = { [weak self] in
          self?.reset()
        }
      }

    }
    ```
  </Step>

  <Step title="Create the connect searcher method">
    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/ios).

    Subscribe to the searcher's `onResults`, and call `increment` for every new search response.

    ```swift Swift icon=code theme={"system"}
    extension SumSearchesInteractor {

      func connectSearcher(_ searcher: HitsSearcher) {
        searcher.onResults.subscribe(with: self) { (interactor, _) in
          interactor.increment()
        }
      }

    }
    ```
  </Step>
</Steps>

## Final touches

You can now use your custom widget in your application, like any other widget:

```swift Swift icon=code theme={"system"}
// Initialize your Searcher as usual
let searcher = try! HitsSearcher(appID: "ALGOLIA_APPLICATION_ID",
                                 apiKey: "ALGOLIA_SEARCH_API_KEY",
                                 indexName: "YourIndexName")

// Create your Interactor and Controller implementation
let sumSearchesInteractor = SumSearchesInteractor()
let sumSearchesButton = UIButton()
let sumSearchesButtonController = SumSearchesButtonController(button: sumSearchesButton)

// Connect your Interactor to start displaying the count of searches
sumSearchesInteractor.connectSearcher(searcher)
sumSearchesInteractor.connectController(sumSearchesButtonController)
```