> ## Documentation Index
> Fetch the complete documentation index at: https://algolia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# RelatedItems

> Finds parameters to retrieve related items.

## About this widget

The `RelatedItems` components computes search parameters to fetch related items.
You pass it a hit, which will be the reference in computing the search parameters and retrieving the related items.

To add `RelatedItems` to your search experience, use these components:

* `Searcher`. A new [`Searcher`](/doc/api-reference/widgets/instantsearch/ios) that handles your searches for related items.
* `HitsInteractor`. The hits interactor to display the related items.
* `HitsController`. The controller that interfaces with a concrete hits view.

In a way, this component acts similarly to the [`Hits`](/doc/api-reference/widgets/hits/ios) component,
but it only modifies the results.

<Card title="Explore example code" icon="github" href="https://github.com/algolia/instantsearch-ios/tree/master/Examples/Showcase">
  Browse the RelatedItems example code on GitHub.
</Card>

## Examples

Connect `HitsInteractor` and `HitsController` with each other using the provided connection method,
and connect the `HitsInteractor` with `Searcher`.
This example uses the `HitsTableController` provided by InstantSearch.

Now, each time you launch a new search:

* `Searcher` receives new results and transmit them to `HitsInteractor`
* `HitsInteractor` parses search results and notifies `HitsController`
* `HitsController` refreshes the view presenting the hits

```swift Swift icon=code theme={"system"}
let searcher = HitsSearcher(appID: "YourApplicationID",
                            apiKey: "YourSearchOnlyAPIKey",
                            indexName: "YourIndexName")
let hitsInteractor: HitsInteractor<JSON> = .init()
let hitsTableViewController = CustomHitsTableViewController()
let matchingPatterns: [MatchingPattern<Product>] =
[
  MatchingPattern(attribute: "brand", score: 3, filterPath: \.brand),
  MatchingPattern(attribute: "categories", score: 2, filterPath: \.categories),
]

let hit: Hit<Product> = .init(objectID: "objectID123", object: product)

override func viewDidLoad() {
  super.viewDidLoad()
  setup()
}

func setup() {
  hitsInteractor.connectSearcher(searcher, withRelatedItemsTo: hit, with: matchingPatterns)
  hitsInteractor.connectController(hitsTableViewController)
  searcher.search()
}
```

## Parameters

<ParamField body="hit" type="Hit<T>" required>
  The reference hit to compute the search parameters to send to Algolia.

  You can retrieve this hit from any location (app state, your backend, the history, etc.).

  ```swift Swift icon=code theme={"system"}
  let product = Product.init(name: "productName", brand: "Amazon", categories: ["Streaming Media Players", "TV & Home Theater"])
  let hit: Hit<Product> = .init(objectID: "1234", object: product)
  ```
</ParamField>

<ParamField body="matchingPatterns" type="[MatchingPattern<T>]" required>
  A schema that creates [scored filters](/doc/guides/managing-results/refine-results/filtering/in-depth/filter-scoring) based on the hit's attributes.

  In the example below, the `brand` value gets a score of 1 while the `category` values gets a score of 2.

  ```swift Swift icon=code theme={"system"}
  struct Product: Codable {
      let name: String
      let brand: String
      let type: String
      let categories: [String]
      let image: URL
  }

  let matchingPatterns: [MatchingPattern<Product>] =
    [
      MatchingPattern(attribute: "brand", score: 1, filterPath: \.brand),
      MatchingPattern(attribute: "categories", score: 2, filterPath: \.categories)
    ]
  ```

  The hit above would generate the following search parameters:

  ```json JSON icon=braces theme={"system"}
  {
    "sumOrFiltersScores": true,
    "facetFilters": ["objectID:-1234"],
    "optionalFilters": [
      ["brand:Amazon<score=1>"],
      [
        [
          "categories:TV & Home Theater<score=2>",
          "categories:Streaming Media Players<score=2>"
        ]
      ]
    ]
  }
  ```
</ParamField>

## Customizing your view

Related items list appear in the controller implementing `HitsController` protocol.
Read more about customizing `Hits` view in the [HitsController documentation](/doc/api-reference/widgets/hits/ios#hitscontroller).