Filter Menu Group

avonni-filter-menu-group

Groups several filter menus together and manages their combined selected values.

Overview

Filter Menu Group is a Lightning Web Component that renders a set of filter menus together and manages their combined selection as a single value.

Use it in your own Lightning Web Components to build faceted filtering for lists, tables, and search results. You control the menus through an items array—each item becomes a filter that can be a checklist (list), a numeric range, or a date-range—and the group exposes the combined selection plus apply/reset buttons and selected-item pills.

Use Cases

• Product catalogs: Filter by category, price range, and rating at once.
• Record lists: Narrow a custom list view by status, owner, and date.
• Dashboards: Provide a filter toolbar above charts and tables.
• Search results: Add facets that refine results as users select values.
• Reports: Combine list and range filters into a single applied value.

---

Variant Guidelines

Variant	Use Case
horizontal	Filter toolbar above a list or table.
vertical	Collapsible filter sidebar with sections.

---

Use Case Examples

Example 1: Faceted filtering for a product list

Scenario: Let users filter products by category, price, and rating, then apply the combined selection.

<!-- productFilters.html -->
<template>
    <avonni-filter-menu-group
        align="left"
        apply-button-label="Apply filters"
        reset-button-label="Clear"
        items={items}
        value={value}
        variant="horizontal"
        onapply={handleApply}
    ></avonni-filter-menu-group>
</template>

// productFilters.js
import { LightningElement } from 'lwc';

export default class ProductFilters extends LightningElement {
    items = [
        {
            name: 'category',
            label: 'Category',
            iconName: 'utility:filterList',
            type: 'list',
            typeAttributes: {
                items: [
                    { label: 'Electronics', value: 'electronics' },
                    { label: 'Clothing', value: 'clothing' }
                ],
                isMultiSelect: true
            }
        },
        {
            name: 'price',
            label: 'Price',
            type: 'range',
            typeAttributes: { min: 0, max: 500, step: 10 }
        }
    ];
    value = { category: ['electronics'] };

    handleApply(event) {
        const applied = event.detail.value; // { category: [...], price: [...] }
    }
}

Result: A horizontal filter toolbar; clicking "Apply filters" fires apply with the combined value keyed by menu name.

Example 2: Live filtering without an apply button

Scenario: Update results instantly as the user changes any filter.

<!-- liveFilters.html -->
<template>
    <avonni-filter-menu-group
        items={items}
        value={value}
        hide-apply-reset-buttons
        onselect={handleSelect}
    ></avonni-filter-menu-group>
</template>

// liveFilters.js
import { LightningElement } from 'lwc';

export default class LiveFilters extends LightningElement {
    items = [/* ...menu definitions... */];
    value = {};

    handleSelect(event) {
        const menuName = event.detail.name;
        const menuValue = event.detail.value;
    }
}

Result: With the buttons hidden, each selection is saved immediately and fires select with the changed menu's name and value.

---

Specifications

Attributes

Name	Description	Type	Default	Required
align	Alignment of the menu group. Valid values include left, center, right. This attribute isn’t supported for the vertical variant.	String	"left"
apply-button-label	Label of the apply button.	String	"Apply"
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
items	Array of menu objects. Each item will be displayed as a filter menu.	AvonniFilterMenuGroupItem[]	—
reset-button-label	Label of the reset button.	String	"Reset"
single-line	If present, the menus are limited to one line. This attribute isn’t supported for the vertical variant.	Boolean	false
value	Value of the menus. The object follows the structure { menuName: menuValue }. Depending on the menu type, its value will have a different type: * list: selected item’s value, or array of selected items' values. * range: array of selected numbers. * date-range: array of ISO 8601 dates.	Object	—
variant	The variant changes the look of the menu group. Accepted variants include horizontal and vertical.	String	"horizontal"
week-start-day	Used by the date-range menu type. Day displayed as the first day of the week. The value has to be a number between 0 and 6, 0 being Sunday, 1 being Monday, and so on until 6.	Number	"Current user's locale"

Methods

Name	Description	Argument Name	Argument Type	Argument Description
apply	Save the currently selected values.
focus	Set the focus on the first focusable element.
focusSearchInput	Set the focus on the search input of the given menu.	name	String	Name of the menu that should receive the focus.
reset	Unselect all values, without saving the change.

Custom Events

apply

The event fired when an "Apply" button is clicked, or a pill removed from the selected items.

The apply event returns the following parameters.

Parameter	Type	Description
name	string	In the horizontal variant, name of the menu that triggered the event.
value	object	Current value of the filter menu group.

The event properties are as follows.

Property	Value	Description
bubbles	false	This event does not bubble.
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.

blur

The event fired when the focus is removed from the filter menu group.

The blur event doesn't return any parameters.

Property	Value	Description
bubbles	false	This event does not bubble.
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 a dropdown is closed (horizontal variant) or a section is closed (vertical variant).

The close event returns the following parameters.

Parameter	Type	Description
name	string	Name of the closed menu.

The event properties are as follows.

Property	Value	Description
bubbles	false	This event does not bubble.
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.

focus

The event fired when the focus is set on the filter menu group.

The focus event doesn't return any parameters.

Property	Value	Description
bubbles	false	This event does not bubble.
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 on the menu. 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.
name	string	Name of the menu that triggered the event.

The event properties are as follows.

Property	Value	Description
bubbles	false	This event does not bubble.
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 list is opened or the search term is modified.

The loadtotalcount event returns the following parameters.

Parameter	Type	Description
name	string	Name of the menu that triggered the event.

The event properties are as follows.

Property	Value	Description
bubbles	false	This event does not bubble.
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 a dropdown is opened (horizontal variant) or a section is opened (vertical variant).

The open event returns the following parameters.

Parameter	Type	Description
name	string	Name of the opened menu.

The event properties are as follows.

Property	Value	Description
bubbles	false	This event does not bubble.
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 a "Reset" button is clicked.

The reset event returns the following parameters.

Parameter	Type	Description
name	string	In the horizontal variant, name of the menu that triggered the event.

The event properties are as follows.

Property	Value	Description
bubbles	false	This event does not bubble.
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 a search input value is changed.

The search event returns the following parameters.

Parameter	Type	Description
name	string	Name of the menu that triggered the event.
value	string	Value of the search input.

The event properties are as follows.

Property	Value	Description
bubbles	false	This event does not bubble.
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

The event fired when a user selects or unselects a value.

The select event returns the following parameters.

Parameter	Type	Description
name	string	Name of the menu.
value	string	Currently displayed value of the menu.

The event properties are as follows.

Property	Value	Description
bubbles	false	This event does not bubble.
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 an "Apply" button is clicked, or a pill removed from the selected items.

The apply event returns the following parameters.

Parameter	Type	Description
name	string	In the horizontal variant, name of the menu that triggered the event.
value	object	Current value of the filter menu group.

The event properties are as follows.

Property	Value	Description
bubbles	false	This event does not bubble.
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.

blur

The event fired when the focus is removed from the filter menu group.

The blur event doesn't return any parameters.

Property	Value	Description
bubbles	false	This event does not bubble.
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 a dropdown is closed (horizontal variant) or a section is closed (vertical variant).

The close event returns the following parameters.

Parameter	Type	Description
name	string	Name of the closed menu.

The event properties are as follows.

Property	Value	Description
bubbles	false	This event does not bubble.
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.

focus

The event fired when the focus is set on the filter menu group.

The focus event doesn't return any parameters.

Property	Value	Description
bubbles	false	This event does not bubble.
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 on the menu. 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.
name	string	Name of the menu that triggered the event.

The event properties are as follows.

Property	Value	Description
bubbles	false	This event does not bubble.
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 list is opened or the search term is modified.

The loadtotalcount event returns the following parameters.

Parameter	Type	Description
name	string	Name of the menu that triggered the event.

The event properties are as follows.

Property	Value	Description
bubbles	false	This event does not bubble.
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 a dropdown is opened (horizontal variant) or a section is opened (vertical variant).

The open event returns the following parameters.

Parameter	Type	Description
name	string	Name of the opened menu.

The event properties are as follows.

Property	Value	Description
bubbles	false	This event does not bubble.
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 a "Reset" button is clicked.

The reset event returns the following parameters.

Parameter	Type	Description
name	string	In the horizontal variant, name of the menu that triggered the event.

The event properties are as follows.

Property	Value	Description
bubbles	false	This event does not bubble.
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 a search input value is changed.

The search event returns the following parameters.

Parameter	Type	Description
name	string	Name of the menu that triggered the event.
value	string	Value of the search input.

The event properties are as follows.

Property	Value	Description
bubbles	false	This event does not bubble.
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

The event fired when a user selects or unselects a value.

The select event returns the following parameters.

Parameter	Type	Description
name	string	Name of the menu.
value	string	Currently displayed value of the menu.

The event properties are as follows.

Property	Value	Description
bubbles	false	This event does not bubble.
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-group-horizontal-menu-button-color-background-selected	color	#eef4ff
--avonni-filter-menu-group-horizontal-menu-button-count-color-background-selected	color	—
--avonni-filter-menu-group-horizontal-menu-button-count-text-color-selected	color	—
--avonni-filter-menu-group-horizontal-more-filter-button-color-background-selected	color	#eef4ff

Key Considerations

• Value structure: value is an object keyed by each menu's name; the value type depends on the menu type (selection for list, number array for range, ISO date array for date-range).
• Apply vs. live: Use hide-apply-button or hide-apply-reset-buttons to save changes immediately instead of requiring an apply click.
• Variant alignment: align only applies to the horizontal variant.
• Infinite loading: The loadmore event fires only when a menu's enableInfiniteLoading type attribute is set.
• Best Practice: Give every item a unique name and key your value object by those names. Use the horizontal variant for a toolbar and vertical for a sidebar.

---

Troubleshooting Common Issues

• Selections not persisting: Bind value to a tracked property and update it in your apply/select handlers; the component is controlled by value.
• A menu shows no options: Verify the item's typeAttributes.items (for list) or min/max (for range) are provided.
• Apply button missing: Confirm hide-apply-button and hide-apply-reset-buttons are not set when you want manual apply.
• If issues persist: Contact our support team at [email protected] for assistance.