When to use it

Use FilterPanel when the page needs a full faceted filtering surface with grouped options, applied state, and a clear open-close model. It is especially useful on mobile and tablet layouts where filters need to live in a drawer-like overlay.

If the filtering need is only a handful of active chips or a single sort control, use lighter browse controls such as ListingToolbar, FilterChip, or SortSelect instead of a full panel.

Composition notes

FilterPanel stays fully controlled:

• filters defines the available groups and options.
• activeFilters is the applied state.
• onFilterChange updates one filter group at a time.
• open and onOpenChange let the shell control the drawer/sidebar behavior.
• productCount connects the panel footer to the visible result set.

Lead with the slot-first anatomy when the brand needs a custom header, summary, or footer treatment. Use the convenience path when the default structure is already the right answer.

Keep the filter schema stable and make sure option values match the backend query model exactly.

Behavior and theming guidance

The panel should help visitors narrow the result set without feeling like a second page. Keep labels clear, group titles short, and counts helpful.

On mobile, prioritize clear close and apply feedback. Visitors should always understand how many results their current selections will affect.