Skip to main content
Signature
FilterListConnector.Tag(
    filters: List<Filter.Tag>,
    filterState: FilterState,
    selectionMode: SelectionMode,
    groupID: FilterGroupID
)

Explore example code

Browse the FilterList (Tag) example code on GitHub.

​
About this widget

FilterList.Tag is a filtering view that displays any kind of tag filters and lets users refine the search results by selecting them. Compared to the RefinementList, which takes its values from the search response facets, this widget displays tag filters that you add yourself.

​
Examples

Kotlin
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 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
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
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

​
filters
List<Filter.Tag>
required
The tag filters to display.
​
filterState
FilterState
required
The FilterState that will hold your filters.
​
selectionMode
SelectionMode
default: Multiple
Whether the list can have Single or Multiple selections.
​
groupID
FilterGroupID
default: FilterGroupID(FilterOperator.And)
The identifier for the group of filters.

​
View

​
view
FilterListView.Tag
required
The view that renders the tag filters.

​
View

​
view
FilterListView.Tag
required
The view that renders the tag filters.
Kotlin
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
    }
}
Last modified on March 23, 2026