Filter menu

Filter menu allows user to filter the data in a table or a list.

Use a menu when items trigger one-shot actions — a filter menu holds selections and stays open across them. Use a filter multi select for the same trigger over a checkbox list with an "All" row: it summarizes the selection on the trigger and reads as an applied filter.

#Example

#Usage

#With icon button

#Groups

A FilterMenuGroup with type="radio" holds one choice (value is a string); type="checkbox" holds many (value is an array). The list stays open across selections, so several filters adjust in one visit — give each group a title when the list holds more than one.

#Size

FilterMenuButton takes the Button sizes: sm, md (default), lg, and xl. Match the size of the controls beside it.

#Disabled

The filter menu button (and icon button) can be disabled.

You can also disable individual filter menu options instead of the entire button.

#Combinations

The pressed treatment belongs to the open state — Chakra's menu trigger sets data-active and aria-expanded itself when the list opens, so it can't render in a static grid.

#FilterMenuButton

#FilterMenuIconButton

#Guidelines

#When to use

• When user should be able to customize the data displayed in a table or a list.

#When not to use

• If the dropdown triggers one-shot actions rather than holding a selection, use a menu instead.
• Filter triggers stay quiet — FilterMenuButton on secondary (the default) or tertiary, FilterMenuIconButton on tertiary (the default) or secondary; the emphasis belongs on the data being filtered.

#Content

• Use sentence case.

#Positioning inside clipped containers

The open list portals to the document body, so an ancestor with overflow: hidden or its own stacking context doesn't clip or cover it. Inside a modal it portals into the modal's dialog instead, which keeps focus inside the modal; if that dialog clips overflow, pass strategy="fixed" so the list keeps its trigger attachment but positions against the viewport.

#Props

#FilterMenu

Root-level component for adding a menu. All menu-related components must be children of FilterMenu.

Name	Default	Description
children	—	ReactNodeMenu button and list.
strategy	"absolute"	"absolute" | "fixed"Positioning strategy for the open list. The list portals to the document body, or into the enclosing modal's dialog, so page ancestors don't clip it. Use "fixed" inside a modal whose dialog clips overflow, or when the trigger can scroll out of view and an absolute list would extend the page's scroll area.

#FilterMenuButton

Button for opening a menu.

Name	Default	Description
isLoading	—	booleanToggles the loading state.
isDisabled	—	booleanToggles the disabled state.
isJustified	—	booleanTake up an entire available container width.
children	—	ReactNodeButton text.
variant	"secondary"	"primary" | "secondary" | "tertiary" | "danger" | "warning" | "link"Button variant, which determines the purpose the button is used for and its appearance.
size	—	"sm" | "md" | "lg" | "xl"Determines the height of the button.
shape	"default"	"default" | "circle"Determines the shape of the button.
icon	—	ComponentType<SVGAttributes<SVGElement>>Primary icon that's displayed on the left. Only icon or imageUrl can be set at the same time.
directionIcon	—	ComponentType<SVGAttributes<SVGElement>>Icon for indicating the direction, displayed on the right side of the button. Used for icons like "arrow right" or "caret down". Pass a component defined outside render: an inline one remounts on every render, which drops clicks on it.
directionIconSize	—	4 | 5 | 6Override the default direction icon size, in space units. Use only when absolutely necessary.
imageUrl	—	stringURL to an image to display on the left. Only icon or imageUrl can be set at the same time.

#FilterMenuIconButton

Icon-only button for opening a menu.

Name	Default	Description
isLoading	false	booleanToggles the loading state.
isDisabled	false	booleanToggles the disabled state.
aria-label	—	stringButton's meaning for screen readers.
icon	—	ComponentType<SVGAttributes<SVGElement>>Button icon.
size	"md"	"2xs" | "xs" | "sm" | "md" | "lg"Determines the height of the button.
shape	"default"	"default" | "circle"Determines the shape of the button
variant	"tertiary"	"primary" | "secondary" | "tertiary" | "danger"Button variant.

#FilterMenuList

Wrapper for groups. Inherits all style props.

Name	Default	Description
children	—	ReactNodeGroups.
surface	—	SurfaceExplicitly set the surface theme advertised to descendant form elements. Useful when bg is a value the surface resolver doesn't recognise – e.g. responsive object syntax, an arbitrary hex, or a token applied via sx instead of bg.
style	—	ChakraBoxProps["style"]Inline styles, merged with the surface-derived style.

#FilterMenuGroup

Name	Default	Description
type	—	"radio" | "checkbox"Selection type. Use radio to allow a single option to be selected. Use checkbox to allow multiple options to be selected.
value	—	string | string[]Selection. When type is "radio", value is always a string. When type is "checkbox", value is always an array of strings.
onChange	—	(value: string) => void | (value: string[]) => voidCallback for when user selects a single or multiple options, depending on the type prop. When type is "radio", value is always a string. When type is "checkbox", value is always an array of strings.
title	—	stringGroup title.
children	—	ReactNodeMenu items.

#FilterMenuOption

Name	Default	Description
isDisabled	—	booleanDetermines if option is disabled.
children	—	ReactNodeOption text.
value	—	stringOption value. Used to identify this option in a selection.