> ## Documentation Index
> Fetch the complete documentation index at: https://algolia.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Hierarchical Menu
> Shows a hierarchical menu to navigate nested categories.
export const FlavorSwitcher = ({current, baseHref = "", options = [], label = "InstantSearch framework"}) => {
if (options.length === 0) {
return
FlavorSwitcher requires at least one option.
;
}
const selected = options.find(option => option.value === current) ?? options[0];
return ;
};
```kotlin Signature theme={"system"}
HierarchicalConnector(
searcher: HitsSearcher,
attribute: String,
filterState: FilterState,
hierarchicalAttributes: List,
separator: String
)
```
Browse the Hierarchical Menu example code on GitHub.
## About this widget
A `Hierarchical Menu` is a component that displays a hierarchical navigation menu, based on facet attributes.
## Examples
```kotlin Kotlin icon=code theme={"system"}
class MyActivity : AppCompatActivity() {
val searcher = HitsSearcher(
applicationID = "YourApplicationID",
apiKey = "YourSearchOnlyAPIKey",
indexName = "YourIndexName"
)
val hierarchicalCategory = "categories"
val hierarchicalCategoryLvl0 = "$categories.lvl0"
val hierarchicalCategoryLvl1 = "$categories.lvl1"
val hierarchicalCategoryLvl2 = "$categories.lvl2"
val hierarchicalAttributes = listOf(
hierarchicalCategoryLvl0,
hierarchicalCategoryLvl1,
hierarchicalCategoryLvl2
)
val filterState = FilterState()
val separator = " > "
val hierarchical = HierarchicalConnector(
searcher = searcher,
attribute = hierarchicalCategory,
filterState = filterState,
hierarchicalAttributes = hierarchicalAttributes,
separator = separator
)
val connection = ConnectionHandler(hierarchical, searcher.connectFilterState(filterState))
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
val view : HierarchicalView = HierarchicalAdapter() // your HierarchicalView implementation
connection += hierarchical.connectView(view, HierarchicalPresenterImpl(separator))
searcher.searchAsync()
}
override fun onDestroy() {
super.onDestroy()
connection.disconnect()
searcher.cancel()
}
}
```
### Low-level API
If you want to fully control the Hierarchical Menu components and connect them manually,
use the following components:
* `Searcher`. The [`Searcher`](/doc/api-reference/widgets/instantsearch/android) that handles your searches.
* `FilterState`. The current state of the filters.
* `HierarchicalViewModel`. The logic applied to the hierarchical facets.
* `HierarchicalView`. The concrete hierarchical view.
* `HierarchicalPresenter`. The presenter that controls the sorting and other settings of the hierarchical menu.
* `HierarchicalItem`. A single node in the hierarchy.
```kotlin Kotlin icon=code theme={"system"}
class MyActivity : AppCompatActivity() {
val searcher = HitsSearcher(
applicationID = "YourApplicationID",
apiKey = "YourSearchOnlyAPIKey",
indexName = "YourIndexName"
)
val filterState = FilterState()
val hierarchicalCategory = "categories"
val hierarchicalCategoryLvl0 = "$categories.lvl0"
val hierarchicalCategoryLvl1 = "$categories.lvl1"
val hierarchicalCategoryLvl2 = "$categories.lvl2"
val hierarchicalAttributes = listOf(
hierarchicalCategoryLvl0,
hierarchicalCategoryLvl1,
hierarchicalCategoryLvl2
)
val separator = " > "
val viewModel = HierarchicalViewModel(hierarchicalCategory, hierarchicalAttributes, separator)
val connection = ConnectionHandler()
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
val view: HierarchicalView = HierarchicalAdapter() // your `HierarchicalView` implementation
connection += searcher.connectFilterState(filterState)
connection += viewModel.connectFilterState(filterState)
connection += viewModel.connectSearcher(searcher)
connection += viewModel.connectView(view, HierarchicalPresenterImpl(separator))
searcher.searchAsync()
}
override fun onDestroy() {
super.onDestroy()
searcher.cancel()
connection.disconnect()
}
}
```
### Compose UI
InstantSearch provides `HierarchicalState` as a state model,
which implements the `HierarchicalView` interface.
You need to connect `HierarchicalState` to the `HierarchicalConnector` or `HierarchicalViewModel` like any other `HierarchicalView` implementation.
```kotlin Kotlin icon=code theme={"system"}
class MyActivity : AppCompatActivity() {
val searcher = HitsSearcher(
applicationID = "YourApplicationID",
apiKey = "YourSearchOnlyAPIKey",
indexName = "YourIndexName"
)
val hierarchicalCategory = "categories"
val hierarchicalCategoryLvl0 = "$categories.lvl0"
val hierarchicalCategoryLvl1 = "$categories.lvl1"
val hierarchicalCategoryLvl2 = "$categories.lvl2"
val hierarchicalAttributes = listOf(
hierarchicalCategoryLvl0,
hierarchicalCategoryLvl1,
hierarchicalCategoryLvl2
)
val filterState = FilterState()
val separator = " > "
val hierarchicalState = HierarchicalState()
val hierarchical = HierarchicalConnector(
searcher = searcher,
attribute = hierarchicalCategory,
filterState = filterState,
hierarchicalAttributes = hierarchicalAttributes,
separator = separator
)
val connections = ConnectionHandler(hierarchical)
init {
connections += searcher.connectFilterState(filterState)
connections += hierarchical.connectView(hierarchicalState, HierarchicalPresenterImpl(separator))
}
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContent {
LazyColumn {
items(hierarchicalState.hierarchicalItems) { item ->
HierarchicalItem( // your own UI composable to display `HierarchicalItem`
item = item,
onClick = { hierarchicalState.onSelectionChanged?.invoke(item.facet.value) }
)
}
}
}
searcher.searchAsync()
}
override fun onDestroy() {
super.onDestroy()
connections.disconnect()
searcher.cancel()
}
}
```
## Parameters
The [`Searcher`](/doc/api-reference/widgets/instantsearch/android#hitssearcher) that handles your searches.
The attribute to filter.
The [`FilterState`](/doc/api-reference/widgets/filter-state/android) that holds your filters.
The names of the hierarchical attributes that you need to target, in ascending order.
The delimiter used to separate hierarchical facets.
Usually something like " > ", including spaces as shown in this example.
## View
The view that renders the hierarchical menu.
How to display the list of `HierarchicalItem`.
Takes a list of `HierarchicalItem` and returns a new list of `HierarchicalItem`.
A `HierarchicalItem` contains a `Facet`, its `level`, and a `displayName`.
```kotlin Kotlin icon=code theme={"system"}
val view: HierarchicalView = HierarchicalAdapter()
val separator = " > "
val presenter = HierarchicalPresenterImpl(separator)
hierarchical.connectView(view, presenter)
// Example of `HierarchicalView` implementation
class HierarchicalAdapter : HierarchicalView,
ListAdapter(DiffUtilItem()) {
override var onSelectionChanged: Callback? = null
override fun onCreateViewHolder(parent: ViewGroup, viewType: Int): HierarchicalViewHolder {
return HierarchicalViewHolder(parent.inflate(R.layout.list_item_selectable, false))
}
override fun onBindViewHolder(holder: HierarchicalViewHolder, position: Int) {
val item = getItem(position)
holder.bind(item) { onSelectionChanged?.invoke(item.facet.value) }
}
override fun setTree(tree: List) {
submitList(tree)
}
}
class DiffUtilItem : DiffUtil.ItemCallback>() {
override fun areItemsTheSame(oldItem: SelectableItem, newItem: SelectableItem): Boolean {
return oldItem.first == newItem.first
}
override fun areContentsTheSame(oldItem: SelectableItem, newItem: SelectableItem): Boolean {
return oldItem == newItem
}
}
```