RefinementList

Shows a list of facets for refining search results.

Signature

FacetListConnector(
    searcher: HitsSearcher,
    filterState: FilterState,
    attribute: String,
    selectionMode: SelectionMode,
    items: List<FacetHits>,
    persistentSelection: Boolean,
    groupID: FilterGroupID,
)

Explore example code

Browse the RefinementList example code on GitHub.

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

Kotlin

class MyActivity : AppCompatActivity() {

  val searcher = HitsSearcher(
      applicationID = "YourApplicationID",
      apiKey = "YourSearchOnlyAPIKey",
      indexName = "YourIndexName"
  )
  val facetList = FacetListConnector(
      searcher = searcher,
      filterState = FilterState(),
      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.

Kotlin

class MyActivity: AppCompatActivity() {
    val searcher = HitsSearcher(
        applicationID = "YourApplicationID",
        apiKey = "YourSearchOnlyAPIKey",
        indexName = "YourIndexName"
    )
    val filterState = FilterState()
    val 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.

Kotlin

class MyActivity : AppCompatActivity() {
    val searcher = HitsSearcher(
        applicationID = "YourApplicationID",
        apiKey = "YourSearchOnlyAPIKey",
        indexName = "YourIndexName"
    )
    val facetListState = FacetListState()
    val facetList = FacetListConnector(
        searcher = searcher,
        filterState = FilterState(),
        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<FacetHits>`
                    selectableFacet = selectableFacet,
                    onClick = { facet -> facetListState.onSelection?.invoke(facet) }
                )
            }
        }
        searcher.searchAsync()
    }

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

Parameters

searcher · HitsSearcher · required

The Searcher that handles your searches.

filterState · FilterState · required

The FilterState that holds your filters.

attribute · String · required

The attribute to filter.

selectionMode · SelectionMode · default: Multiple

Whether the list can have Single or Multiple selections.

items · List<FacetHits> · default: listOf()

If specified, the default facet values to display.

persistentSelection · Boolean · default: false

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

groupID · FilterGroupID · default: FilterGroupID(attribute, FilterOperator.Or)

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

Use filters or facet filters for more complex result refinement.

View

view · FacetListView · required

The view that renders the facets.

presenter · FacetListPresenter · default: "null"

The presenter that controls the sorting and other settings of the facet list view.

Kotlin

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

Presenter

sortBy · List<FacetSortCriterion> · default: "listOf(FacetSortCriterion.CountDescending)"

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

• FacetSortCriterion.IsRefined
• FacetSortCriterion.CountAscending
• FacetSortCriterion.CountDescending
• FacetSortCriterion.AlphabeticalAscending
• FacetSortCriterion.AlphabeticalDescending

Kotlin

// 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 · Int · default: 10

The number of facet values to retrieve.

Kotlin

FacetListPresenterImpl(limit = 5)