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.

<!-- filterBar.html -->
<template>
    <div class="slds-grid slds-gutters">
        <avonni-filter-menu
            label="Region"
            icon-name="utility:world"
            type="list"
            type-attributes={listTypeAttributes}
            value={regionValue}
            apply-button-label="Apply filter"
            reset-button-label="Clear"
            onselect={handleSelect}
            onapply={handleApply}
            onsearch={handleSearch}
        ></avonni-filter-menu>

        <avonni-filter-menu
            label="Price"
            icon-name="utility:currency"
            type="range"
            type-attributes={rangeTypeAttributes}
            value={priceValue}
            hide-apply-reset-buttons
            onapply={handleApply}
        ></avonni-filter-menu>
    </div>
</template>

// 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.

<!-- statusFilter.html -->
<template>
    <avonni-filter-menu
        label="Status"
        variant="vertical"
        collapsible
        type="list"
        type-attributes={statusTypeAttributes}
        value={statusValue}
        onselect={handleSelect}
        onapply={handleApply}
    ></avonni-filter-menu>
</template>

// 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"
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
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.

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 [email protected] for assistance.