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

# Filter Map

> Applies a selected filter from a predefined map.

```swift Signature theme={"system"}
FilterMapConnector(
  searcher: HitsSearcher,
  filterState: FilterState,
  items: [Int: Filter],
  selected: Int,
  attribute: Attribute,
  operator: RefinementOperator,
  groupName: String?
)
```

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

## About this widget

Components holding a map of filters, and that can apply a single filter at a time.

## Examples

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

  let searcher: HitsSearcher
  let filterState: FilterState
  let filterMapConnector: FilterMapConnector<Filter.Facet>
  let controller = SegmentedController<Filter.Facet>(segmentedControl: .init())

  init() {
    let gender: Attribute = "gender"
    let male = Filter.Facet(attribute: "gender", stringValue: "male")
    let female = Filter.Facet(attribute: "gender", stringValue: "female")
    let notSpecified = Filter.Facet(attribute: "gender", stringValue: "not specified")
    let items: [Int: Filter.Facet] = [
      0: male,
      1: female,
      2: notSpecified,
    ]

    self.searcher = HitsSearcher(appID: "YourApplicationID",
                                 apiKey: "YourAPIKey",
                                 indexName: "YourIndexName")

    self.filterState = FilterState()
    self.filterMapConnector = .init(searcher: searcher,
                                    filterState: filterState,
                                    items: items,
                                    selected: 0,
                                    attribute: gender,
                                    operator: .or,
                                    controller: controller,
                                    presenter: DefaultPresenter.Filter.present)
    searcher.connectFilterState(filterState)
    searcher.search()
  }

}
```

### Low-level API

If you want to fully control the Filter Map components and connect them manually, use the following components:

* `Searcher`. The [`Searcher`](/doc/api-reference/widgets/instantsearch/ios) that handles searches.
* `FilterState`. The current state of the filters.
* `FilterMapInteractor`. The logic applied to the filter map.
* `FilterMapController`. The view that renders the filter map.

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

  let searcher: HitsSearcher
  let filterState: FilterState
  let filterMapInteractor: FilterMapInteractor<Filter.Facet>
  let controller = SegmentedController<Filter.Facet>(segmentedControl: .init())

  init() {
    let gender: Attribute = "gender"
    let male = Filter.Facet(attribute: "gender", stringValue: "male")
    let female = Filter.Facet(attribute: "gender", stringValue: "female")
    let notSpecified = Filter.Facet(attribute: "gender", stringValue: "not specified")

    self.searcher = HitsSearcher(appID: "YourApplicationID",
                                 apiKey: "YourAPIKey",
                                 indexName: "YourIndexName")
    let items: [Int: Filter.Facet] = [
      0: male,
      1: female,
      2: notSpecified,
    ]
    self.filterState = FilterState()
    self.filterMapInteractor = .init(items: items,
                                     selected: 0)
    searcher.connectFilterState(filterState)
    filterMapInteractor.connectSearcher(searcher, attribute: gender)
    filterMapInteractor.connectFilterState(filterState,
                                           attribute: gender,
                                           operator: .or)
    filterMapInteractor.connectController(controller,
                                          presenter: DefaultPresenter.Filter.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 filters.
</ParamField>

<ParamField body="items" type="[Int: Filter]" required>
  The map of filters to be held.
  The key is an unique identifier for the filter value.

  ```swift Swift icon=code theme={"system"}
  let gender = Attribute("gender")
  let filters = [
    0: Filter.Facet(attribute: gender, value:  "male"),
    1: Filter.Facet(attribute: gender, value: "female")
    2: Filter.Facet(attribute: gender, value: "not specified")
  ]
  ```
</ParamField>

<ParamField body="selected" type="Int" required>
  The key of the filter selected by default.
</ParamField>

<ParamField body="attribute" type="Attribute" required>
  The attribute to filter.
</ParamField>

<ParamField body="operator" type="RefinementOperator" required>
  Whether facets are combined with `and` or `or` behavior in `filterState`.
  For example if you select `color` as the attribute and an `or` behavior,
  the filter sent to Algolia is `color:red OR color:green`.
</ParamField>

<ParamField body="groupName" type="String?" default=".none">
  Filter group name.
</ParamField>

## Controller

<ParamField body="controller" type="SelectableSegmentController" required>
  The view that renders the filter map.
</ParamField>

<ParamField body="presenter" default="DefaultPresenter.Filter.present">
  How to display filters.

  ```swift Swift icon=code theme={"system"}
  let controller = SegmentedController<Filter.Facet>(segmentedControl: .init())
  let presenter = DefaultPresenter.Filter.present
  filterMap.connectController(controller, presenter: presenter)
  ```
</ParamField>