Skip to main content
Signature
FacetListConnector(
    searcher: HitsSearcher,
    filterState: FilterState,
    attribute: Attribute,
    selectionMode: SelectionMode,
    items: List<Facet>,
    persistentSelection: Boolean,
    groupID: FilterGroupID,
)
Explore example code

​
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 = 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.
Kotlin
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.
Kotlin
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
HitsSearcher
required
The Searcher that handles your searches.
​
filterState
FilterState
required
The FilterState that holds your filters.
​
attribute
Attribute
required
The attribute to filter.
​
selectionMode
SelectionMode
default: Multiple
Whether the list can have Single or Multiple selections.
​
items
List<Facet>
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)
⌘I