Create your own widgets

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

Starting May 1, 2024, Apple requires all iOS apps to include a privacy manifest. For more information, see Privacy manifest.

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

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 to describe what you’re trying to build.

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.

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

   class SumSearchesInteractor {
   
     var sum: Int = 0 {
       didSet {
         onSumChanged.fire(sum)
       }
     }
   
     public let onSumChanged: Observer<Int> = .init()
   
     func increment() {
       sum += 1
     }
   
     func reset() {
       sum = 0
     }
   
   }
   
2. 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

   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
   }
   
3. Implement the controller

   The SumSearchesButtonController should display the data received in setSum and trigger onReset when clicked.

   Swift

   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?()
     }
   
   }
   
4. 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

   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()
       }
     }
   
   }
   
5. 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.

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

   Swift

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

Final touches

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

Swift

// Initialize your Searcher as usual
let searcher = 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)