API Reference / Android Widgets / Refinement List

Refinement List

About this widget

RefinementList is a filtering view that displays facets, and lets the user refine their search results by filtering on specific values.

To add a RefinementList to your search experience, use these components:

  • Searcher: The Searcher that handles your searches.
  • FilterState: The current state of the filters.
  • FacetListViewModel: The logic applied to the facets.
  • FacetListView: The view that will render facets.
  • FacetListPresenter: Optional. The presenter that controls the sorting and other settings of the facet list view.

Examples

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
class MyActivity: AppCompatActivity() {

    class MyFacetListViewHolder(view: View): FacetListViewHolder(view) {

        override fun bind(facet: Facet, selected: Boolean, onClickListener: View.OnClickListener) {
           // Bind your view
        }

        object Factory: FacetListViewHolder.Factory {

            override fun createViewHolder(parent: ViewGroup): FacetListViewHolder {
                // Inflate your layout
                val view = View(parent.context)

                return MyFacetListViewHolder(view)
            }
        }
    }

    val client = ClientSearch(
        ApplicationID("YourApplicationID"),
        APIKey("YourAPIKey")
    )
    val index = client.initIndex(IndexName("YourIndexName"))
    val searcher = SearcherSingleIndex(index)
    val filterState = FilterState()
    val attribute = Attribute("facetName")
    val viewModel = FacetListViewModel()
    val presenter = FacetListPresenterImpl(listOf(FacetSortCriterion.CountDescending), limit = 5)
    val connection = ConnectionHandler()

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        // You can use the default FacetListAdapter, or implement your own UI component that fulfill the FacetListView interface.
        val view: FacetListView = FacetListAdapter(MyFacetListViewHolder.Factory)

        connection += searcher.connectFilterState(filterState)
        connection += viewModel.connectFilterState(filterState, attribute, FilterOperator.Or)
        connection += viewModel.connectSearcher(searcher, attribute)
        connection += viewModel.connectView(view, presenter)

        searcher.searchAsync()
    }

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

Parameters

searcher
type: Searcher
Required

The Searcher that handles your searches.

1
viewModel.connectSearcher(searcher)
filterState
type: FilterState
Required

The FilterState that will hold your filters.

1
viewModel.connectFilterState(filterState)
facetListView
type: FacetListView
Required

The view that will render the facets.

1
viewModel.connectView(facetListView)
attribute
type: Attribute
Required

The attribute to filter.

1
2
val attribute = Attribute("category")
viewModel.connectFilterState(filterState, attribute)
operator
type: FilterOperator
default: FilterOperator.And
Optional

Whether we apply an And or Or behavior to the facets in the filterState.

For example if we have color as attribute and an or behavior,
the filter sent to Algolia will be color:red OR color:green.

1
viewModel.connectFilterState(filterState, attribute, FilterOperator.Or)
items
type: List<Facet>
default: listOf()
Optional

If specified, the default facet values to display.

1
FacetListViewModel(items = listOf(Facet(Attribute("foo"), "bar")))
selectionMode
type: SelectionMode
default: Multiple
Optional

Whether the list can have Single or Multiple selections.

1
FacetListViewModel(items, selectionMode = SelectionMode.Multiple)
persistentSelection
type: Boolean
default: false
Optional

When true, the selection will be kept even if it does not match current results anymore.

1
FacetListViewModel(items, persistentSelection = true)

Presenter

sortBy
type: List<FacetSortCriterion>
default: listOf(FacetSortCriterion.CountDescending)
Optional

How to sort facets. Must be one or more of the following values:

  • FacetSortCriterion.IsRefined
  • FacetSortCriterion.CountAscending
  • FacetSortCriterion.CountDescending
  • FacetSortCriterion.AlphabeticalAscending
  • FacetSortCriterion.AlphabeticalDescending
1
2
3
4
// Tie breaking algorithm where we show refined values first.
// In case of a tie, we show the facets that have the biggest counts.
// In case of a tie, we show the facets in alphabetical order.
FacetListPresenterImpl(listOf(IsRefined, CountDescending, AlphabeticalAscending))
limit
type: Int
default: 10
Optional

The number of facet values to retrieve.

1
FacetListPresenterImpl(limit = 5)

Did you find this page helpful?