UI libraries / InstantSearch Android / Widgets

Refinement List

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

About this widget

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

Requirements

The attribute provided to the widget must be 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 write your own UI component that implements 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

Filters operator, which can either be FilterOperator.And or FilterOperator.Or.

Use filters or facet filters for more complex result refinement.

View

view
type: FacetListView
Required

The view that renders 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 refined values are shown first.
// If refined values are tied, show the facets with the largest counts.
// If counts are tied, show 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