API Reference / InstantSearch Android / Refinement List

Refinement List

Signature 
FacetListConnector(
  searcher: HitsSearcher,
  filterState: FilterState,
  attribute: Attribute,
  selectionMode: SelectionMode,
  items: List<Facet>,
  persistentSelection: Boolean,
  groupID: FilterGroupID,
)
See code examples

About this widget

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

Requirements

You need to add the attribute you provide to the widget in attributes for faceting, either on the dashboard or using the attributesForFaceting parameter with the API.

Examples

Copy 
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

class MyActivity : AppCompatActivity() {

  val searcher = HitsSearcher(
      applicationID = ApplicationID("YourApplicationID"),
      apiKey = APIKey("YourSearchOnlyAPIKey"),
      indexName = IndexName("YourIndexName")
  )
  val facetList = FacetListConnector(
      searcher = searcher,
      filterState = FilterState(),
      attribute = Attribute("facetName"),
      selectionMode = SelectionMode.Multiple
  )
  val connection = ConnectionHandler(facetList)

  override fun onCreate(savedInstanceState: Bundle?) {
      super.onCreate(savedInstanceState)
      // You can use the default `FacetListAdapter`, or implement your own UI component that implements the `FacetListView` interface.
      val facetListAdapter = FacetListAdapter(FacetListViewHolderImpl.Factory)
      connection += facetList.connectView(facetListAdapter)
      searcher.searchAsync()
  }

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

Low-level API

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

  • FilterState: The current state of the filters.
  • FacetListViewModel: The logic applied to the facets.
  • FacetListView: The view that renders facets.
  • FacetListPresenter: Optional. The presenter that controls the sorting and other settings of the facet list view.
Copy 
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

class MyActivity: AppCompatActivity() {
    val searcher = HitsSearcher(
        applicationID = ApplicationID("YourApplicationID"),
        apiKey = APIKey("YourSearchOnlyAPIKey"),
        indexName = IndexName("YourIndexName")
    )
    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()
    }
}

Compose UI

InstantSearch provides the FacetListState as a state model, which is an implementation of the FacetListView interface. You need to connect FacetListState to the FacetListConnector or FacetListViewModel like any other FacetListView implementation.

Copy 
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

class MyActivity : AppCompatActivity() {
    val searcher = HitsSearcher(
        applicationID = ApplicationID("YourApplicationID"),
        apiKey = APIKey("YourSearchOnlyAPIKey"),
        indexName = IndexName("YourIndexName")
    )
    val facetListState = FacetListState()
    val facetList = FacetListConnector(
        searcher = searcher,
        filterState = FilterState(),
        attribute = Attribute("facetName"),
        selectionMode = SelectionMode.Multiple
    )
    val connections = ConnectionHandler(facetList)

    init {
        connections += facetList.connectView(facetListState)
    }

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        // You can use the default `FacetListAdapter`, or implement your own UI component that implements the `FacetListView` interface.
        setContent {
            facetListState.items.forEach { selectableFacet ->
                FacetRow( // your own UI composable to display `SelectableItem<Facet>`
                    selectableFacet = selectableFacet,
                    onClick = { facet -> facetListState.onSelection?.invoke(facet) }
                )
            }
        }
        searcher.searchAsync()
    }

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

Parameters

searcher
type: HitsSearcher
Required

The Searcher that handles your searches.
filterState
type: FilterState
Required

The FilterState that holds your filters.
attribute
type: Attribute
Required

The attribute to filter.
selectionMode
type: SelectionMode
default: Multiple
Optional

Whether the list can have Single or Multiple selections.
items
type: List<Facet>
default: listOf()
Optional

If specified, the default facet values to display.
persistentSelection
type: Boolean
default: false
Optional

When true, the selection will be kept even if it does not match current results anymore.
groupID
type: FilterGroupID
default: FilterGroupID(attribute, FilterOperator.Or)
Optional

The identifier of the group of filters.

View

view
type: FacetListView
Required

The view that render the facets.
presenter
type: FacetListPresenter
default: null
Optional

The presenter that controls the sorting and other settings of the facet list view.
Copy 
1
2
3

val facetListAdapter = FacetListAdapter(FacetListViewHolderImpl.Factory)
val facetListPresenter = FacetListPresenterImpl(listOf(FacetSortCriterion.CountDescending, FacetSortCriterion.AlphabeticalAscending))
facetListCategory.connectView(facetListAdapter, facetListPresenter)

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
Copy 
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.
Copy 
1

FacetListPresenterImpl(limit = 5)
Did you find this page helpful?
InstantSearch Android v3