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

# Hierarchical Menu

> Shows a hierarchical menu to navigate nested categories.

```swift Signature theme={"system"}
HierarchicalConnector(
  searcher: SingleIndexSearcher,
  filterState: FilterState,
  hierarchicalAttributes: [Attribute],
  separator: String,
  controller: HierarchicalController,
  presenter: HierarchicalPresenter
)
```

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

## About this widget

A `Hierarchical Menu` is a component that displays a hierarchical navigation menu, based on facet attributes.

## Examples

Instantiate a `HierarchicalConnector` and launch an initial search on its [`Searcher`](/doc/api-reference/widgets/instantsearch/ios).

```swift Swift icon=code theme={"system"}
let searcher = HitsSearcher(appID: "YourApplicationID",
                            apiKey: "YourSearchOnlyAPIKey",
                            indexName: "YourIndexName")

let filterState: FilterState = .init()

searcher.connectFilterState(filterState)

let hierarchicalAttributes: [Attribute] = [
  "categories.lvl0",
  "categories.lvl1",
  "categories.lvl2",
]

let hierarchicalTableViewController: HierarchicalTableViewController = .init(tableView: UITableView())

let hierachicalConnector: HierarchicalConnector = .init(searcher: searcher,
                                                        filterState: filterState,
                                                        hierarchicalAttributes: hierarchicalAttributes,
                                                        separator: " > ",
                                                        controller: hierarchicalTableViewController,
                                                        presenter: DefaultPresenter.Hierarchical.present)
searcher.search()
```

## Parameters

<ParamField body="searcher" type="HitsSearcher" required>
  The [`Searcher`](/doc/api-reference/widgets/instantsearch/ios) that handles your searches.
</ParamField>

<ParamField body="filterState" type="FilterState" required>
  The [`FilterState`](/doc/api-reference/widgets/filter-state/ios) that holds your filters.
</ParamField>

<ParamField body="hierarchicalAttributes" type="[Attribute]" required>
  The names of the hierarchical attributes to target, in ascending order.
</ParamField>

<ParamField body="separator" type="String" required>
  The delimiter used to separate hierarchical facets.
  Usually something like " > ", including spaces as shown in this example.
</ParamField>

<ParamField body="controller" type="HierarchicalController" post={["default: nil"]}>
  The Controller interfacing with a concrete hierarchical view.
</ParamField>

<ParamField body="presenter" type="HierarchicalPresenter" post={["default: nil"]}>
  The Presenter defining how hierarchical facets appear in the controller.
</ParamField>

## Presenter

<ParamField body="Hierarchical Presenter" type="(([HierarchicalFacet]) -> [HierarchicalFacet])?" default="nil">
  The presenter defining how to display the `HierarchicalFacet` list.

  Takes a list of `HierarchicalFacet` as input and returns a new `HierarchicalFacet` list.

  A `HierarchicalFacet` is a tuple of a `Facet`, its `level`, and whether it's `selected` or not.

  ```swift Swift icon=code theme={"system"}
  public static let present: HierarchicalPresenter = { facets in
      let levels = Set(facets.map { $0.level }).sorted()

      guard !levels.isEmpty else { return facets }

      var output: [HierarchicalFacet] = []

      output.reserveCapacity(facets.count)

      levels.forEach { level in
        let facetsForLevel = facets
          .filter { $0.level == level }
          .sorted { $0.facet.value < $1.facet.value }
        let indexToInsert = output
          .lastIndex { $0.isSelected }
          .flatMap { output.index(after: $0) } ?? output.endIndex
        output.insert(contentsOf: facetsForLevel, at: indexToInsert)
      }

      return output
    }
  ```
</ParamField>

## Low-level API

If you want to fully control the `Hierarchical Menu` components and connect them manually, you can use the following components:

* `Searcher`. The [`Searcher`](/doc/api-reference/widgets/instantsearch/ios) that handles your searches.
* `FilterState`. The current state of the filters.
* `HierarchicalInteractor`. The logic applied to the hierarchical facets.
* `HierarchicalController`. The controller that interfaces with a concrete hierarchical facet list view.
* `HierarchicalPresenter`. Optional. The presenter that controls the sorting and other settings of the refinement facet list view.

```swift Swift icon=code theme={"system"}
let searcher = HitsSearcher(appID: "YourApplicationID",
                            apiKey: "YourSearchOnlyAPIKey",
                            indexName: "YourIndexName")

let filterState: FilterState = .init()

let hierarchicalAttributes: [Attribute] = [
  "categories.lvl0",
  "categories.lvl1",
  "categories.lvl2",
]

let hierarchicalTableViewController: HierarchicalTableViewController = .init(tableView: UITableView())

let hierarchicalInteractor: HierarchicalInteractor = .init(hierarchicalAttributes: hierarchicalAttributes,
                                                           separator: " > ")

searcher.connectFilterState(filterState)
hierarchicalInteractor.connectSearcher(searcher: searcher)
hierarchicalInteractor.connectFilterState(filterState)
hierarchicalInteractor.connectController(hierarchicalTableViewController)

searcher.search()
```

## Customizing your view

The default controllers, for example, `HierarchicalTableViewController`,
work well when you want to use native UIKit with their default behavior.

If you want to use another component such as a `UICollectionView`,
a third-party input view,
or you want to introduce some custom behavior to the already provided UIKit component,
you can create your own controller conforming to the `HierarchicalController` protocol.

### Protocol

`var onClick: ((String) -> Void)?`:

Closure to call when a new hierarchical facet is clicked.

`func setItem(_ item: [HierarchicalFacet])`

Function called when a new array of hierarchical facets is updated. This is the UI State of the refinement list. Make sure to reload your view here when you get the new items.

### Example

```swift Swift icon=code theme={"system"}
open class HierarchicalTableViewController: NSObject, HierarchicalController {

  public var onClick: ((String) -> Void)?
  var items: [HierarchicalFacet]
  var tableView: UITableView
  let cellID: String

  public init(tableView: UITableView, cellID: String = "HierarchicalFacet") {
    self.tableView = tableView
    self.items = []
    self.cellID = cellID

    super.init()

    tableView.register(UITableViewCell.self, forCellReuseIdentifier: cellID)
    tableView.dataSource = self
    tableView.delegate = self
  }

  public func setItem(_ item: [HierarchicalFacet]) {

    self.items = item

    tableView.reloadData()
  }

}

extension HierarchicalTableViewController: UITableViewDataSource {

  open func tableView(_ tableView: UITableView, numberOfRowsInSection section: Int) -> Int {
    return items.count
  }

  open func tableView(_ tableView: UITableView, cellForRowAt indexPath: IndexPath) -> UITableViewCell {
    let cell = tableView.dequeueReusableCell(withIdentifier: cellID, for: indexPath)

    let maxSelectedLevel = Set(items.filter { $0.isSelected }.map { $0.level }).max() ?? 0
    let item = items[indexPath.row]
    cell.textLabel?.text = "\(item.facet.description)"
    cell.indentationLevel = item.level
    cell.accessoryType = item.level == maxSelectedLevel && item.isSelected ? .checkmark : .none
    return cell

  }
}

extension HierarchicalTableViewController: UITableViewDelegate {
  open func tableView(_ tableView: UITableView, didSelectRowAt indexPath: IndexPath) {
    let item = items[indexPath.row]
    onClick?(item.facet.value)
  }
}
```

### SwiftUI

InstantSearch provides the `HierarchicalList` SwiftUI view which you can embed in your views.
It uses `HierarchicalObservableController` as a data model,
which is an implementation of the `HierarchicalController` protocol adapted for usage with SwiftUI.
`HierarchicalObservableController` must be connected to the `HierarchicalConnector` or `HierarchicalInteractor` like any other `HierarchicalController` implementation.
You can define the appearance of the view representing a single hierarchical facet and its selection state or use the `HierarchicalFacetRow` view provided by InstantSearch.

```swift Swift icon=code theme={"system"}
struct ContentView: View {

  @ObservedObject let hierarchicalController: HierarchicalObservableController

  var body: some View {
    HierarchicalList(hierarchicalController) { facet, nestingLevel, isSelected in
      // Use the implementation provided by InstantSearch
      // HierarchicalFacetRow(facet: facet,
                              nestingLevel: nestingLevel,
                              isSelected: isSelected)
      // Or declare a custom single hierarchical facet view
      HStack(spacing: 10) {
        Image(systemName: isSelected ? "chevron.down" : "chevron.right")
          .font(.callout)
        Text("\(facet.value) (\(facet.count))")
          .fontWeight(isSelected ? .semibold : .regular)
          .contentShape(Rectangle())
        Spacer()
      }
      .padding(.leading, CGFloat(nestingLevel * 20))
    }
  }

}
```

If you prefer to create a custom SwiftUI view that presents the list of hierarchical facets,
you can directly use the `HierarchicalObservableController` as a data model.
It provides the `hierarchicalFacets` property along with the `toggle` function to streamline the design process of your custom SwiftUI view.