> For the complete documentation index, see [llms.txt](https://docs.avonnicomponents.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.avonnicomponents.com/lwc-components/core-components/filter-menu.md).
# Filter Menu
`avonni-filter-menu`
A menu that lets users filter data by selecting from a list of values, a range or dates.
## Overview
**Filter Menu** is a Lightning Web Component that lets users filter data by a list of items, a numeric range, a date range, or a time range, presented either as a dropdown button (horizontal) or an inline collapsible section (vertical).
Use it in your own Lightning Web Components to build filter bars and faceted search panels. You choose the filter type, supply type-specific attributes, and read the selection from the `select` and `apply` events.
### Use Cases
* **Faceted search:** Combine list filters for region, status, and category.
* **Price ranges:** Filter products by a numeric range with a slider.
* **Date filtering:** Narrow records to a date range.
* **Time windows:** Filter by a time-of-day range.
* **Sidebar filters:** Use the vertical variant for a collapsible filter panel.
***
## Variant Guidelines
| Variant | Use Case |
| ------------ | ----------------------------------------------------- |
| `horizontal` | Compact filter bar where each filter is a dropdown. |
| `vertical` | Sidebar/faceted panel with collapsible filter groups. |
***
## Use Case Examples
### Example 1: List and range filters in a horizontal bar
**Scenario:** Build a filter bar with a multi-select region list and an apply-on-change price range.
```html
```
```js
// filterBar.js
import { LightningElement } from 'lwc';
export default class FilterBar extends LightningElement {
listTypeAttributes = {
isMultiSelect: true,
allowSearch: true,
searchInputPlaceholder: 'Search regions...',
items: [
{ label: 'North America', value: 'na' },
{ label: 'Europe', value: 'eu' },
{ label: 'Asia', value: 'as' }
]
};
rangeTypeAttributes = {
min: 0,
max: 500,
step: 25,
unit: 'currency',
unitAttributes: { currencyCode: 'USD' }
};
regionValue = ['eu', 'as'];
priceValue = [50, 300];
handleApply(event) {
const value = event.detail.value; // applied filter value
}
handleSelect(event) {
const pending = event.detail.value; // not yet saved
}
handleSearch(event) {
const term = event.detail.value;
}
}
```
**Result:** A region dropdown with searchable multi-select that applies on the Apply button, and a price slider that applies immediately on change.
### Example 2: Vertical collapsible status filter
**Scenario:** Add a sidebar status filter as a collapsible vertical section with color-coded options.
```html
```
```js
// statusFilter.js
import { LightningElement } from 'lwc';
export default class StatusFilter extends LightningElement {
statusTypeAttributes = {
isMultiSelect: true,
items: [
{ label: 'New', value: 'new', color: '#1589ee' },
{ label: 'In Progress', value: 'in-progress', color: '#ffb75d' },
{ label: 'Completed', value: 'completed', color: '#2e844a' }
]
};
statusValue = ['new'];
handleApply(event) {
const value = event.detail.value;
}
handleSelect(event) {
const pending = event.detail.value;
}
}
```
**Result:** A collapsible vertical filter section with color-coded status checkboxes; selections fire `select`, and applying fires `apply`.
***
## Specifications
### Attributes
| Name | Description | Type | Default | Required |
| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ | --------------------------------------- | -------- |
| `access-key` | The keyboard shortcut for the button menu (horizontal variant) or the checkbox group (vertical variant). | String | — | |
| `alternative-text` | The assistive text for the button menu. This attribute isn’t supported for the vertical variant. | String | `"Show Menu"` | |
| `apply-button-label` | Label of the apply button. | String | `"Apply"` | |
| `button-variant` | The button variant changes the look of the horizontal variant’s button. Accepted variants include bare, container, border, border-filled, bare-inverse, and border-inverse. This attribute isn’t supported for the vertical variant. | String | `"border"` | |
| `closed` | If present, close the collapsible section. This attribute is only supported by the vertical variant. | Boolean | `false` | |
| `collapsible` | If present, the headers are collapsible. This attribute is only supported by the vertical variant. | Boolean | `false` | |
| `disabled` | If present, the menu cannot be used by users. | Boolean | `false` | |
| `dropdown-alignment` | Determines the alignment of the dropdown menu relative to the button. Available options are: auto, left, center, right, bottom-left, bottom-center, bottom-right. The auto option aligns the dropdown menu based on available space. This attribute isn’t supported for the vertical variant. | String | `"left"` | |
| `dropdown-nubbin` | If present, a nubbin is present on the dropdown menu. A nubbin is a stub that protrudes from the menu item towards the button menu. The nubbin position is based on the menu-alignment. This attribute isn’t supported for the vertical variant. | Boolean | `false` | |
| `group-order` | Reserved for internal use only. Describes the order of this element inside `lightning-button-group`. Valid values include first, middle or last. | String | — | |
| `hide-apply-button` | If present, the apply button is hidden and the value is immediately saved every time the selection changes. | Boolean | `false` | |
| `hide-apply-reset-buttons` | If present, the apply and reset buttons are hidden and the value is immediately saved every time the selection changes. | Boolean | `false` | |
| `hide-selected-items` | If present, the selected items are hidden. | Boolean | `false` | |
| `icon-name` | The name of the icon to be used in the format 'utility:down'. For the horizontal variant, if an icon other than 'utility:down' or 'utility:chevrondown' is used, a utility:down icon is appended to the right of that icon. | String | `"utility:down for horizontal variant"` | |
| `icon-size` | The size of the icon. Options include xx-small, x-small, small, medium or large. This value defaults to medium. | String | `"medium"` | |
| `is-loading` | If present, the menu is in a loading state and shows a spinner. | Boolean | `false` | |
| `label` | Label of the menu. | String | — | |
| `loading-state-alternative-text` | Message displayed while the menu is in the loading state. | String | `"Loading"` | |
| `name` | Specifies the name of the filter menu. | String | — | |
| `reset-button-label` | Label of the reset button. | String | `"Reset"` | |
| `title` | Title of the button (horizontal variant) or the label (vertical variant). | String | — | |
| `tooltip` | The tooltip is displayed on hover or focus on the button (horizontal variant), or on the help icon (vertical variant). | String | — | |
| `type` | Type of the filter menu. Valid values include list, range, date-range and time-range. | String | `"list"` | |
| `type-attributes` | Attributes specific to the type. | AvonniFilterMenuTypeAttributes | — | |
| `value` | Value of the filter menu. If the type is `list`, array of selected items values. If the type is `range`, array of selected numbers. If the type is `date-range`, array of ISO 8601 dates. If the type is `time-range`, array of time strings in the format HH:mm\[:ss\[.SSS]]. | String\[] | Number\[] | Date\[] |
| `variant` | The variant changes the look of the menu. Accepted variants include horizontal and vertical. | String | `"horizontal"` | |
### Methods
| Name | Description | Argument Name | Argument Type | Argument Description |
| ------------------ | ---------------------------------------------------------------------------------------------- | ------------- | ------------- | -------------------- |
| `apply` | Save the currently selected values. | | | |
| `focus` | Set the focus on the filter menu button (horizontal variant) or choice set (vertical variant). | | | |
| `focusSearchInput` | Set the focus on the search input. | | | |
| `reset` | Unselect all values, without saving the change. | | | |
### Custom Events
#### `apply`
The event fired when the “Apply” button is clicked, or a pill removed from the selected items. If `hide-apply-reset-buttons` is `true`, the `apply` event is also fired when the user selects or unselects a value.
The `apply` event returns the following parameters.
| Parameter | Type | Description |
| --------- | --------- | ----------- |
| `value` | string\[] | number\[] |
The event properties are as follows.
| Property | Value | Description |
| ---------- | ----- | --------------------------------------------------------------------------------------------------------- |
| bubbles | true | This event bubbles up through the DOM. |
| cancelable | false | This event has no default behavior that can be canceled. You can't call `preventDefault()` on this event. |
| composed | false | This event does not propagate outside of the component in which it was dispatched. |
#### `close`
The event fired when the dropdown is closed (horizontal variant) or the section is closed (vertical variant).
The `close` event doesn't return any parameters.
| Property | Value | Description |
| ---------- | ----- | --------------------------------------------------------------------------------------------------------- |
| bubbles | true | This event bubbles up through the DOM. |
| cancelable | false | This event has no default behavior that can be canceled. You can't call `preventDefault()` on this event. |
| composed | false | This event does not propagate outside of the component in which it was dispatched. |
#### `loadmore`
The event fired when the end of a list is reached. It is only fired if the `enableInfiniteLoading` type attribute is present. In the horizontal variant, the `loadmore` event is triggered by a scroll to the end of the list. In the vertical variant, the `loadmore` event is triggered by a button clicked by the user or by a nested item opening.
The `loadmore` event returns the following parameters.
| Parameter | Type | Description |
| --------- | ------ | --------------------------------------------------------------------- |
| `item` | object | If the event was triggered by a nested item, definition of this item. |
The event properties are as follows.
| Property | Value | Description |
| ---------- | ----- | --------------------------------------------------------------------------------------------------------- |
| bubbles | true | This event bubbles up through the DOM. |
| cancelable | false | This event has no default behavior that can be canceled. You can't call `preventDefault()` on this event. |
| composed | false | This event does not propagate outside of the component in which it was dispatched. |
#### `loadtotalcount`
The event fired when the total count of the list items is unknown.
The `loadtotalcount` event doesn't return any parameters.
| Property | Value | Description |
| ---------- | ----- | --------------------------------------------------------------------------------------------------------- |
| bubbles | true | This event bubbles up through the DOM. |
| cancelable | false | This event has no default behavior that can be canceled. You can't call `preventDefault()` on this event. |
| composed | false | This event does not propagate outside of the component in which it was dispatched. |
#### `open`
The event fired when the dropdown is opened (horizontal variant) or the section is opened (vertical variant).
The `open` event doesn't return any parameters.
| Property | Value | Description |
| ---------- | ----- | --------------------------------------------------------------------------------------------------------- |
| bubbles | true | This event bubbles up through the DOM. |
| cancelable | false | This event has no default behavior that can be canceled. You can't call `preventDefault()` on this event. |
| composed | false | This event does not propagate outside of the component in which it was dispatched. |
#### `reset`
The event fired when the selection is resetted.
The `reset` event doesn't return any parameters.
| Property | Value | Description |
| ---------- | ----- | --------------------------------------------------------------------------------------------------------- |
| bubbles | true | This event bubbles up through the DOM. |
| cancelable | false | This event has no default behavior that can be canceled. You can't call `preventDefault()` on this event. |
| composed | false | This event does not propagate outside of the component in which it was dispatched. |
#### `search`
The event fired when the search input value is changed.
The `search` event returns the following parameters.
| Parameter | Type | Description |
| --------- | ------ | ------------------------------ |
| `value` | string | The value of the search input. |
The event properties are as follows.
| Property | Value | Description |
| ---------- | ----- | --------------------------------------------------------------------------------------------------------- |
| bubbles | true | This event bubbles up through the DOM. |
| cancelable | false | This event has no default behavior that can be canceled. You can't call `preventDefault()` on this event. |
| composed | false | This event does not propagate outside of the component in which it was dispatched. |
#### `select`
TThe event fired when a user selects or unselects a value.
The `select` event returns the following parameters.
| Parameter | Type | Description |
| --------- | --------- | ----------------------------------------------------------------------------------------------------------- |
| `value` | string\[] | Currently selected value. The value is not saved, as long as the user does not click on the “apply” button. |
The event properties are as follows.
| Property | Value | Description |
| ---------- | ----- | --------------------------------------------------------------------------------------------------------- |
| bubbles | true | This event bubbles up through the DOM. |
| cancelable | false | This event has no default behavior that can be canceled. You can't call `preventDefault()` on this event. |
| composed | false | This event does not propagate outside of the component in which it was dispatched. |
### Styling Hooks
| CSS Variable | Type | Default |
| ------------------------------------------------------------------------ | --------- | ----------- |
| `--avonni-filter-menu-horizontal-button-color-background-selected` | color | `#eef4ff` |
| `--avonni-filter-menu-horizontal-button-count-background-color-selected` | color | — |
| `--avonni-filter-menu-horizontal-button-count-text-color-selected` | color | — |
| `--avonni-filter-menu-vertical-collapse-icon-color-foreground` | color | — |
| `--avonni-filter-menu-vertical-label-color-background` | color | `#ffffff` |
| `--avonni-filter-menu-vertical-label-color-background-active` | color | — |
| `--avonni-filter-menu-vertical-label-color-background-hover` | color | — |
| `--avonni-filter-menu-vertical-label-font-size` | dimension | `0.8125rem` |
| `--avonni-filter-menu-vertical-label-font-weight` | number | `700` |
| `--avonni-filter-menu-vertical-label-text-color` | color | `#181818` |
| `--avonni-filter-menu-vertical-label-text-color-active` | color | — |
| `--avonni-filter-menu-vertical-label-text-color-hover` | color | — |
| `--avonni-filter-menu-vertical-load-more-button-text-color` | color | — |
| `--avonni-filter-menu-vertical-load-more-button-text-color-active` | color | — |
| `--avonni-filter-menu-vertical-load-more-button-text-color-hover` | color | — |
## Key Considerations
* **Type drives shape:** `value` and `type-attributes` differ by `type`—items for `list`, `min`/`max` for `range`, ISO dates for `date-range`, time strings for `time-range`.
* **Select vs apply:** `select` fires on every change (unsaved); `apply` fires when the value is committed.
* **Immediate apply:** Set `hide-apply-reset-buttons` to commit on every change with no Apply button.
* **Variant features:** `collapsible`, `closed`, and the vertical layout are vertical-only; dropdown alignment and button variant are horizontal-only.
* **Infinite loading:** Combine the `enableInfiniteLoading` type attribute with the `loadmore` event for large lists.
* **Best Practice:** Match `type` to the data and pass the right shape in `type-attributes` (e.g. `items` for `list`, `min`/`max` for `range`).
***
## Troubleshooting Common Issues
* **No items in a list filter:** Confirm `type="list"` and that `type-attributes.items` is a non-empty array.
* **Value not applying:** Read `event.detail.value` from `apply` (not `select`), unless `hide-apply-reset-buttons` is set.
* **Vertical-only attribute ignored:** Attributes like `collapsible` and `closed` only take effect with `variant="vertical"`.
* **If issues persist:** Contact our support team at for assistance.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.avonnicomponents.com/lwc-components/core-components/filter-menu.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.