FilterList (Facet)

Signature

FilterListConnector.Facet(
    filters: List<Filter.Facet>,
    filterState: FilterState,
    selectionMode: SelectionMode,
    groupID: FilterGroupID
)

Explore example code

Browse the FilterList (Facet) example code on GitHub.

FilterList.Facet is a filtering view that displays any kind of facet filters and lets users refine their search results by selecting them. Compared to the RefinementList, which takes its values from the search response facets, this widget displays facet 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 color = "color"
    val groupColor = groupAnd(color)
    val facetFilters = listOf(
        Filter.Facet(color, "red"),
        Filter.Facet(color, "green"),
        Filter.Facet(color, "blue"),
        Filter.Facet(color, "yellow"),
        Filter.Facet(color, "black")
    )
    val filterListConnector = FilterListConnector.Facet(
        filters = facetFilters,
        filterState = filterState,
        selectionMode = SelectionMode.Single,
        groupID = groupColor
    )
    val connection = ConnectionHandler(filterListConnector, searcher.connectFilterState(filterState))

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        val filterListView: FilterListView.Facet = MyFilterListFacetAdapter() // your `FilterListView.Facet` 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.Facet components and connect them manually, use the following components:

Searcher: The Searcher that handles your searches.
FilterState: The current state of the filters.
FilterListViewModel.Facet: The logic applied to the facet filters.
FilterListView.Facet: The view that renders the facet 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 color = "color"
    val filters = listOf(
        Filter.Facet(color, "red"),
        Filter.Facet(color, "green"),
        Filter.Facet(color, "blue"),
        Filter.Facet(color, "yellow"),
        Filter.Facet(color, "black")
    )
    val viewModel = FilterListViewModel.Facet(filters)
    val connection = ConnectionHandler()

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        val view: FilterListView.Facet = MyFilterListFacetAdapter() // your `FilterListView.Facet` 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 color = "color"
    val groupColor = groupAnd(color)
    val facetFilters = listOf(
        Filter.Facet(color, "red"),
        Filter.Facet(color, "green"),
        Filter.Facet(color, "blue"),
        Filter.Facet(color, "yellow"),
        Filter.Facet(color, "black")
    )
    val filterListState = FilterListState<Filter.Facet>()
    val filterListConnector = FilterListConnector.Facet(
        filters = facetFilters,
        filterState = filterState,
        selectionMode = SelectionMode.Single,
        groupID = groupColor
    )
    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.Facet>`
                    selectableFilter = selectableFacet,
                    onClick = { filterListState.onSelection?.invoke(it) }
                )
            }
        }
        searcher.searchAsync()
    }

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

Parameters

filters

List<Filter.Facet>

required

default: listOf()

The facet 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.Or)

The identifier for the group of filters.

View

view

FilterListView.Facet

The view that renders the filters.

Kotlin

import com.algolia.instantsearch.filter.Filter

val view: FilterListView.Facet = MyFilterListFacetAdapter()
filterListConnector.connectView(view)

// Example of FilterListView.Facet implementation
class MyFilterListFacetAdapter : FilterListView.Facet,
    ListAdapter<SelectableItem<Filter.Facet>, FilterListViewHolder>(DiffUtilItem()) {

    override var onSelection: Callback<Filter.Facet>? = 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.Facet>>) {
        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
    }
}

InstantSearch Android

FilterList (Facet)

Explore example code

About this widget

Examples

Low-level API

Compose UI

Parameters

View

Explore example code

​About this widget

​Examples

​Low-level API

​Compose UI

​Parameters

​View

About this widget

Examples

Low-level API

Compose UI

Parameters

View