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

# FilterList (Tag)

> Shows a list of tag filters for refining search results.

<div className="not-prose algolia-flavor-switcher">
  <div className="afs-dropdown">
    <div className="afs-trigger" role="button" tabIndex="0" aria-haspopup="listbox">
      <span className="afs-current">Android</span>

      <svg className="afs-chevron lucide lucide-chevron-down" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
        <path d="m6 9 6 6 6-6" />
      </svg>
    </div>

    <ul className="afs-menu" role="listbox">
      <li role="option" aria-selected="false"><a className="afs-option" href="/doc/api-reference/widgets/filter-list-tag/ios"><span className="afs-option-name">iOS</span><span className="afs-option-lib">InstantSearch iOS</span></a></li>
      <li role="option" aria-selected="true"><a className="afs-option is-current" href="/doc/api-reference/widgets/filter-list-tag/android"><span className="afs-option-name">Android</span><span className="afs-option-lib">InstantSearch Android</span></a></li>
    </ul>
  </div>
</div>

```kotlin Signature theme={"system"}
FilterListConnector.Tag(
    filters: List<Filter.Tag>,
    filterState: FilterState,
    selectionMode: SelectionMode,
    groupID: FilterGroupID
)
```

<Card title="Explore example code" icon="github" href="https://github.com/algolia/instantsearch-android/tree/master/examples/android">
  Browse the FilterList (Tag) example code on GitHub.
</Card>

## About this widget

`FilterList.Tag` is a filtering view that displays any kind of [tag filters](/doc/api-reference/api-parameters/tagFilters) and lets users refine the search results by selecting them.

Compared to the [`RefinementList`](/doc/api-reference/widgets/refinement-list/android),
which takes its values from the search response facets, this widget displays tag filters that you add yourself.

## Examples

```kotlin Kotlin icon=code theme={"system"}
import com.algolia.instantsearch.filter.Filter

class MyActivity : AppCompatActivity() {
    val searcher = HitsSearcher(
        applicationID = "YourApplicationID",
        apiKey = "YourSearchOnlyAPIKey",
        indexName = "YourIndexName"
    )
    val filterState = FilterState()
    val tags = "_tags"
    val groupTags = groupOr(tags)
    val filters = listOf(
        Filter.Tag("free shipping"),
        Filter.Tag("coupon"),
        Filter.Tag("free return"),
        Filter.Tag("on sale"),
        Filter.Tag("no exchange")
    )
    val filterListConnector = FilterListConnector.Tag(
        filters = filters,
        filterState = filterState,
        groupID = groupTags
    )

    val connection = ConnectionHandler(filterListConnector, searcher.connectFilterState(filterState))

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        val filterListView: FilterListView.Tag = MyFilterListTagAdapter() // your `FilterListView.Tag` implementation
        connection += filterListConnector.connectView(filterListView)
        searcher.searchAsync()
    }

    override fun onDestroy() {
        super.onDestroy()
        connection.disconnect()
        searcher.cancel()
    }
}
```

### Low-level API

If you want to fully control the `FilterList.Tag` components and connect them manually, use the following components:

* `Searcher`. The [`Searcher`](/doc/api-reference/widgets/instantsearch/android) that handles your searches.
* `FilterState`. The current state of the filters.
* `FilterListViewModel.Tag`. The logic applied to the tag filters.
* `FilterListView.Tag`. The view that renders the tag filters.
* `FilterPresenter`. Optional. The presenter to customize the display of the filters.

```kotlin Kotlin icon=code theme={"system"}
import com.algolia.instantsearch.filter.Filter

class MyActivity : AppCompatActivity() {
    val searcher = HitsSearcher(
        applicationID = "YourApplicationID",
        apiKey = "YourSearchOnlyAPIKey",
        indexName = "YourIndexName"
    )
    val filterState = FilterState()
    val filters = listOf(
        Filter.Tag("free shipping"),
        Filter.Tag("coupon"),
        Filter.Tag("free return"),
        Filter.Tag("on sale"),
        Filter.Tag("no exchange")
    )
    val viewModel = FilterListViewModel.Tag(filters)
    val connection = ConnectionHandler()

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        val view: FilterListView.Tag = MyFilterListTagAdapter() // your `FilterListView.Tag` implementation
        connection += searcher.connectFilterState(filterState)
        connection += viewModel.connectFilterState(filterState)
        connection += viewModel.connectView(view)

        searcher.searchAsync()
    }

    override fun onDestroy() {
        super.onDestroy()
        connection.disconnect()
        searcher.cancel()
    }
}
```

### Compose UI

InstantSearch provides the `FilterListState` as a state model, which is an implementation of the `FilterListView` interface.
You need to connect `FilterListState` to the `FilterListConnector` or `FilterListViewModel` like any other `FilterListView` implementation.

```kotlin Kotlin icon=code theme={"system"}
import com.algolia.instantsearch.filter.Filter

class MyActivity : AppCompatActivity() {
    val searcher = HitsSearcher(
        applicationID = "YourApplicationID",
        apiKey = "YourSearchOnlyAPIKey",
        indexName = "YourIndexName"
    )
    val filterState = FilterState()
    val tags = "_tags"
    val groupTags = groupOr(tags)
    val filters = listOf(
        Filter.Tag("free shipping"),
        Filter.Tag("coupon"),
        Filter.Tag("free return"),
        Filter.Tag("on sale"),
        Filter.Tag("no exchange")
    )
    val filterListState = FilterListState<Filter.Tag>()
    val filterListConnector = FilterListConnector.Tag(
        filters = filters,
        filterState = filterState,
        groupID = groupTags
    )

    val connections = ConnectionHandler(filterListConnector)

    init {
        connections += searcher.connectFilterState(filterState)
        connections += filterListConnector.connectView(filterListState)
    }

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContent {
            filterListState.items.forEach { selectableFacet ->
                FilterRow( // your own UI composable to display `SelectableItem<Filter.Tag>`
                    selectableFilter = selectableFacet,
                    onClick = { filterListState.onSelection?.invoke(it) }
                )
            }
        }
        searcher.searchAsync()
    }

    override fun onDestroy() {
        super.onDestroy()
        connections.disconnect()
        searcher.cancel()
    }
}
```

## Parameters

<ParamField body="filters" type="List<Filter.Tag>" required>
  The tag filters to display.
</ParamField>

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

<ParamField body="selectionMode" type="SelectionMode" post={["default: Multiple"]}>
  Whether the list can have `Single` or `Multiple` selections.
</ParamField>

<ParamField body="groupID" type="FilterGroupID" post={["default: FilterGroupID(FilterOperator.And)"]}>
  The identifier for the group of filters.
</ParamField>

## View

<ParamField body="view" type="FilterListView.Tag" required>
  The view that renders the tag filters.
</ParamField>

## View

<ParamField body="view" type="FilterListView.Tag" required>
  The view that renders the tag filters.

  ```kotlin Kotlin icon=code theme={"system"}
  import com.algolia.instantsearch.filter.Filter

  val view: FilterListView.Tag = MyFilterListView()
  filterListConnector.connectView(view)

  // Example of `FilterListView.Tag` implementation
  class MyFilterListTagAdapter : FilterListView.Tag,
      ListAdapter<SelectableItem<Filter.Tag>, FilterListViewHolder>(DiffUtilItem()) {
      override var onSelection: Callback<Filter.Tag>? = null
      override fun onCreateViewHolder(parent: ViewGroup, viewType: Int): FilterListViewHolder {
          return FilterListViewHolder(parent.inflate(R.layout.list_item_selectable))
      }

      override fun onBindViewHolder(holder: FilterListViewHolder, position: Int) {
          val (filter, selected) = getItem(position)
          holder.bind(FilterPresenterImpl()(filter), selected) { onSelection?.invoke(filter) }
      }

      override fun setItems(items: List<SelectableItem<Filter.Tag>>) {
          submitList(items)
      }
  }

  class DiffUtilItem<T : Filter> : DiffUtil.ItemCallback<SelectableItem<T>>() {
      override fun areItemsTheSame(oldItem: SelectableItem<T>, newItem: SelectableItem<T>): Boolean {
          return oldItem.first == newItem.first
      }

      override fun areContentsTheSame(oldItem: SelectableItem<T>, newItem: SelectableItem<T>): Boolean {
          return oldItem == newItem
      }
  }
  ```
</ParamField>