Refinement List
FacetListConnector( searcher: HitsSearcher, filterState: FilterState, attribute: Attribute, selectionMode: SelectionMode, items: List<Facet>, persistentSelection: Boolean, groupID: FilterGroupID, )
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
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.
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.
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
| Parameter | Description | 
|---|---|
          
            searcher
          
         | 
        
           
                
                type: HitsSearcher
                
               
              
                
                        Required
                
               
          The   | 
      
          
            filterState
          
         | 
        
           
                
                type: FilterState
                
               
              
                
                        Required
                
               
          The   | 
      
          
            attribute
          
         | 
        
           
                
                type: Attribute
                
               
              
                
                        Required
                
               
          The attribute to filter.  | 
      
          
            selectionMode
          
         | 
        
           
                
                type: SelectionMode
                
               
              
                
                  default: Multiple
                
               
              
                
                    Optional
                
               
          Whether the list can have   | 
      
          
            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
| Parameter | Description | ||
|---|---|---|---|
          
            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
 
       | 
      |||
Presenter
| Parameter | Description | ||
|---|---|---|---|
          
            sortBy
          
         | 
        
           
                
                type: List<FacetSortCriterion>
                
               
              
                
                  default: listOf(FacetSortCriterion.CountDescending)
                
               
              
                
                    Optional
                
               
          How to sort facets. Must be one or more of the following values: 
  | 
      ||
| 
           
Copy
 
       | 
      |||
          
            limit
          
         | 
        
           
                
                type: Int
                
               
              
                
                  default: 10
                
               
              
                
                    Optional
                
               
          The number of facet values to retrieve.  | 
      ||
| 
           
Copy
 
       | 
      |||