> 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. Users also choose how the filter compares — an operator menu titled **Filter mode** sits at the top of the filter — and the chosen operator is returned with the value by both 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-operators` | If present, the operators are hidden and the default operator for the type is always applied. | 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 | — | |
| `operator` | Operator applied to the value. Valid values include between, notBetween, eq, ne, lt, lte, gt, gte, null and notNull. | String | `"eq for the list type, between for the date-range, range and time-range types"` | |
| `reset-button-label` | Label of the reset button. | String | `"Reset"` | |
| `reset-button-position` | The position of the reset button. Valid values include top and bottom. Default to bottom. This attribute is only supported by the vertical variant. | String | `"bottom"` | |
| `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 |
| ---------- | -------------------- | ----------------------------- |
| `operator` | string | Operator of the filter. |
| `value` | string\[]\|number\[] | New value of the filter menu. |
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 |
| ---------- | --------- | ----------------------------------------------------------------------------------------------------------- |
| `operator` | string | Operator of the filter. |
| `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.
* **Operators:** The **Filter mode** menu sets how the filter compares. A `list` filter offers Equals, Not Equals, Empty and Not Empty; the `range`, `date-range` and `time-range` types offer those plus Between, Not Between, Less Than, Less or Equal, Greater Than and Greater or Equal. When `operator` is unset, a `list` filter defaults to Equals and the `range`, `date-range` and `time-range` types default to Between. Set `hide-operators` to hide the menu and always apply that default.
* **Operators and the value shape:** Between and Not Between are the only operators that read two bounds; Empty and Not Empty need no value at all, so `value` comes back as an empty array while `operator` carries the filter.
* **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"`.
* **No Filter mode menu:** `hide-operators` hides it, and the type's default operator is applied instead — Equals for a `list` filter, Between for `range`, `date-range` and `time-range`.
* **An operator is missing from the menu:** A `list` filter exposes only Equals, Not Equals, Empty and Not Empty; use `range`, `date-range` or `time-range` for the comparison operators.
* **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 by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
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 what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
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.