> 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-group.md).

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

```html
<!-- 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>
```

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

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

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

### 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 <support@avonni.app> 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-group.md?ask=<question>&goal=<endgoal>
```

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