The padding required to prevent the arrow from reaching the very edge of the popper.
Menu
An accessible dropdown menu for the common dropdown menu button design pattern. Menu uses roving tabIndex for focus management.
Props#
Menu Props#
arrowPadding
arrowPaddingDescription
Type
numberDefault
8autoSelect
autoSelectDescription
If true, the first enabled menu item will receive focus and be selected
when the menu opens.
Type
booleanDefault
trueboundary
boundaryDescription
The boundary area for the popper. Used within the preventOverflow modifier
Type
"clippingParents" | "scrollParent" | HTMLElementDefault
clippingParentscloseOnBlur
closeOnBlurDescription
If true, the menu will close when you click outside
the menu list
Type
booleanDefault
truecloseOnSelect
closeOnSelectDescription
If true, the menu will close when a menu item is
clicked
Type
booleanDefault
truecomputePositionOnMount
computePositionOnMountType
booleandefaultIsOpen
defaultIsOpenType
booleandirection
directionDescription
If rtl, poper placement positions will be flipped i.e. 'top-right' will
become 'top-left' and vice-verse
Type
"ltr" | "rtl"eventListeners
eventListenersDescription
If provided, determines whether the popper will reposition itself on scroll
and resize of the window.
Type
type ONLY_FOR_FORMAT =
| boolean
| { scroll?: boolean | undefined resize?: boolean | undefined }Default
trueflip
flipDescription
If true, the popper will change its placement and flip when it's
about to overflow its boundary area.
Type
booleanDefault
truegutter
gutterDescription
The distance or margin between the reference and popper.
It is used internally to create an offset modifier.
NB: If you define offset prop, it'll override the gutter.
Type
numberDefault
8id
idType
stringinitialFocusRef
initialFocusRefDescription
The ref of the element that should receive focus when the popover opens.
Type
RefObject<{ focus(): void }>isLazy
isLazyDescription
Performance 🚀:
If true, the MenuItem rendering will be deferred
until the menu is open.
Type
booleanDefault
falseisOpen
isOpenType
booleanlazyBehavior
lazyBehaviorDescription
Performance 🚀: The lazy behavior of menu's content when not visible. Only works when `isLazy={true}` - "unmount": The menu's content is always unmounted when not open. - "keepMounted": The menu's content initially unmounted, but stays mounted when menu is open.
Type
LazyModeDefault
unmountmatchWidth
matchWidthDescription
If true, the popper will match the width of the reference at all times.
It's useful for autocomplete, `date-picker` and select patterns.
Type
booleanDefault
falsemodifiers
modifiersDescription
Array of popper.js modifiers. Check the docs to see the list of possible modifiers you can pass.
Type
Partial<Modifier<string, any>>[]offset
offsetDescription
The main and cross-axis offset to displace popper element from its reference element.
Type
[number, number]onClose
onCloseType
() => voidonOpen
onOpenType
() => voidplacement
placementDescription
The placement of the popper relative to its reference.
Type
PlacementWithLogicalDefault
bottompreventOverflow
preventOverflowDescription
If true, will prevent the popper from being cut off and ensure
it's visible within the boundary area.
Type
booleanDefault
truestrategy
strategyDescription
The CSS positioning strategy to use.
Type
"absolute" | "fixed"Default
absoluteMenuButton Props#
MenuButton composes Box so you can pass all
Box props to change its style.
MenuList Props#
MenuList composes Box so you can pass all Box
props to change its style.
motionProps
motionPropsDescription
The framer-motion props to animate the menu list
Type
HTMLMotionProps<"div">rootProps
rootPropsDescription
Props for the root element that positions the menu.
Type
HTMLChakraProps<"div">MenuItem Props#
closeOnSelect
closeOnSelectDescription
Overrides the parent menu's closeOnSelect prop.
Type
booleancommand
commandDescription
Right-aligned label text content, useful for displaying hotkeys.
Type
stringcommandSpacing
commandSpacingDescription
The spacing between the command and menu item's label.
Type
ResponsiveValue<string | number | (string & {})>icon
iconDescription
The icon to render before the menu item's label.
Type
ReactElement<any, string | JSXElementConstructor<any>>iconSpacing
iconSpacingDescription
The spacing between the icon and menu item's label.
Type
ResponsiveValue<string | number | (string & {})>isDisabled
isDisabledDescription
If true, the menuitem will be disabled
Type
booleanisFocusable
isFocusableDescription
If true and the menuitem is disabled, it'll
remain keyboard-focusable
Type
booleanMenuGroup Props#
MenuGroup composes Box so you can pass all
Box props to change its style.
MenuOptionGroup Props#
defaultValue
defaultValueType
string | string[]onChange
onChangeType
(value: string | string[]) => voidtype
typeType
"radio" | "checkbox"value
valueType
string | string[]MenuItemOption Props#
MenuItemOption composes Box so you can pass all
box props in addition to these:
closeOnSelect
closeOnSelectDescription
Overrides the parent menu's closeOnSelect prop.
Type
booleancommand
commandDescription
Right-aligned label text content, useful for displaying hotkeys.
Type
stringcommandSpacing
commandSpacingDescription
The spacing between the command and menu item's label.
Type
ResponsiveValue<string | number | (string & {})>icon
iconType
ReactElement<any, string | JSXElementConstructor<any>>iconSpacing
iconSpacingDescription
The spacing between the icon and menu item's label.
Type
ResponsiveValue<string | number | (string & {})>isChecked
isCheckedType
booleanisDisabled
isDisabledDescription
If true, the menuitem will be disabled
Type
booleanisFocusable
isFocusableDescription
If true and the menuitem is disabled, it'll
remain keyboard-focusable
Type
booleantype
typeType
"radio" | "checkbox"value
valueType
stringProps#
Menu Props#
arrowPadding
arrowPaddingDescription
The padding required to prevent the arrow from reaching the very edge of the popper.
Type
numberDefault
8autoSelect
autoSelectDescription
If true, the first enabled menu item will receive focus and be selected
when the menu opens.
Type
booleanDefault
trueboundary
boundaryDescription
The boundary area for the popper. Used within the preventOverflow modifier
Type
"clippingParents" | "scrollParent" | HTMLElementDefault
clippingParentscloseOnBlur
closeOnBlurDescription
If true, the menu will close when you click outside
the menu list
Type
booleanDefault
truecloseOnSelect
closeOnSelectDescription
If true, the menu will close when a menu item is
clicked
Type
booleanDefault
truecomputePositionOnMount
computePositionOnMountType
booleandefaultIsOpen
defaultIsOpenType
booleandirection
directionDescription
If rtl, poper placement positions will be flipped i.e. 'top-right' will
become 'top-left' and vice-verse
Type
"ltr" | "rtl"eventListeners
eventListenersDescription
If provided, determines whether the popper will reposition itself on scroll
and resize of the window.
Type
type ONLY_FOR_FORMAT =
| boolean
| { scroll?: boolean | undefined resize?: boolean | undefined }Default
trueflip
flipDescription
If true, the popper will change its placement and flip when it's
about to overflow its boundary area.
Type
booleanDefault
truegutter
gutterDescription
The distance or margin between the reference and popper.
It is used internally to create an offset modifier.
NB: If you define offset prop, it'll override the gutter.
Type
numberDefault
8id
idType
stringinitialFocusRef
initialFocusRefDescription
The ref of the element that should receive focus when the popover opens.
Type
RefObject<{ focus(): void }>isLazy
isLazyDescription
Performance 🚀:
If true, the MenuItem rendering will be deferred
until the menu is open.
Type
booleanDefault
falseisOpen
isOpenType
booleanlazyBehavior
lazyBehaviorDescription
Performance 🚀: The lazy behavior of menu's content when not visible. Only works when `isLazy={true}` - "unmount": The menu's content is always unmounted when not open. - "keepMounted": The menu's content initially unmounted, but stays mounted when menu is open.
Type
LazyModeDefault
unmountmatchWidth
matchWidthDescription
If true, the popper will match the width of the reference at all times.
It's useful for autocomplete, `date-picker` and select patterns.
Type
booleanDefault
falsemodifiers
modifiersDescription
Array of popper.js modifiers. Check the docs to see the list of possible modifiers you can pass.
Type
Partial<Modifier<string, any>>[]offset
offsetDescription
The main and cross-axis offset to displace popper element from its reference element.
Type
[number, number]onClose
onCloseType
() => voidonOpen
onOpenType
() => voidplacement
placementDescription
The placement of the popper relative to its reference.
Type
PlacementWithLogicalDefault
bottompreventOverflow
preventOverflowDescription
If true, will prevent the popper from being cut off and ensure
it's visible within the boundary area.
Type
booleanDefault
truestrategy
strategyDescription
The CSS positioning strategy to use.
Type
"absolute" | "fixed"Default
absoluteMenuButton Props#
MenuButton composes Box so you can pass all
Box props to change its style.
MenuList Props#
MenuList composes Box so you can pass all Box
props to change its style.
motionProps
motionPropsDescription
The framer-motion props to animate the menu list
Type
HTMLMotionProps<"div">rootProps
rootPropsDescription
Props for the root element that positions the menu.
Type
HTMLChakraProps<"div">MenuItem Props#
closeOnSelect
closeOnSelectDescription
Overrides the parent menu's closeOnSelect prop.
Type
booleancommand
commandDescription
Right-aligned label text content, useful for displaying hotkeys.
Type
stringcommandSpacing
commandSpacingDescription
The spacing between the command and menu item's label.
Type
ResponsiveValue<string | number | (string & {})>icon
iconDescription
The icon to render before the menu item's label.
Type
ReactElement<any, string | JSXElementConstructor<any>>iconSpacing
iconSpacingDescription
The spacing between the icon and menu item's label.
Type
ResponsiveValue<string | number | (string & {})>isDisabled
isDisabledDescription
If true, the menuitem will be disabled
Type
booleanisFocusable
isFocusableDescription
If true and the menuitem is disabled, it'll
remain keyboard-focusable
Type
booleanMenuGroup Props#
MenuGroup composes Box so you can pass all
Box props to change its style.
MenuOptionGroup Props#
defaultValue
defaultValueType
string | string[]onChange
onChangeType
(value: string | string[]) => voidtype
typeType
"radio" | "checkbox"value
valueType
string | string[]MenuItemOption Props#
MenuItemOption composes Box so you can pass all
box props in addition to these:
closeOnSelect
closeOnSelectDescription
Overrides the parent menu's closeOnSelect prop.
Type
booleancommand
commandDescription
Right-aligned label text content, useful for displaying hotkeys.
Type
stringcommandSpacing
commandSpacingDescription
The spacing between the command and menu item's label.
Type
ResponsiveValue<string | number | (string & {})>icon
iconType
ReactElement<any, string | JSXElementConstructor<any>>iconSpacing
iconSpacingDescription
The spacing between the icon and menu item's label.
Type
ResponsiveValue<string | number | (string & {})>isChecked
isCheckedType
booleanisDisabled
isDisabledDescription
If true, the menuitem will be disabled
Type
booleanisFocusable
isFocusableDescription
If true and the menuitem is disabled, it'll
remain keyboard-focusable
Type
booleantype
typeType
"radio" | "checkbox"value
valueType
stringThe Menu component is a multipart component. The styling needs to be applied
to each part specifically.
To learn more about styling multipart components, visit the Component Style page.
Anatomy#
- A:
button - B:
list - C:
item - D:
groupTitle - E:
command - F:
divider
Theming properties#
The properties that affect the theming of the Menu component are:
variant: The visual variant of the component. There is no default applied.size: The size of the component. There is no default applied.
Theming utilities#
createMultiStyleConfigHelpers: a function that returns a set of utilities for creating style configs for a multipart component (definePartsStyleanddefineMultiStyleConfig).definePartsStyle: a function used to create multipart style objects.defineMultiStyleConfig: a function used to define the style configuration for a multipart component.
import { menuAnatomy } from '@chakra-ui/anatomy'import { createMultiStyleConfigHelpers, defineStyle } from '@fluidtruck/core'const { definePartsStyle, defineMultiStyleConfig } =createMultiStyleConfigHelpers(menuAnatomy.keys)
Customizing the default theme#
import { menuAnatomy } from '@chakra-ui/anatomy'import { createMultiStyleConfigHelpers, defineStyle } from '@fluidtruck/core'const { definePartsStyle, defineMultiStyleConfig } =createMultiStyleConfigHelpers(menuAnatomy.keys)// define the base component stylesconst baseStyle = definePartsStyle({// define the part you're going to stylebutton: {// this will style the MenuButton componentfontWeight: 'medium',bg: 'teal.500',color: 'gray.200',_hover: {bg: 'teal.600',color: 'white',},},list: {// this will style the MenuList componentpy: '4',borderRadius: 'xl',border: 'none',bg: 'teal.500',},item: {// this will style the MenuItem and MenuItemOption componentscolor: 'gray.200',_hover: {bg: 'teal.600',},_focus: {bg: 'teal.600',},},groupTitle: {// this will style the text defined by the title prop// in the MenuGroup and MenuOptionGroup componentstextTransform: 'uppercase',color: 'white',textAlign: 'center',letterSpacing: 'wider',opacity: '0.7',},command: {// this will style the text defined by the command// prop in the MenuItem and MenuItemOption componentsopacity: '0.8',fontFamily: 'mono',fontSize: 'sm',letterSpacing: 'tighter',pl: '4',},divider: {// this will style the MenuDivider componentmy: '4',borderColor: 'white',borderBottom: '2px dotted',},})// export the base styles in the component themeexport const menuTheme = defineMultiStyleConfig({ baseStyle })
After customizing the input theme, we can import it into our theme file and add
it in the components property:
import { extendTheme } from '@fluidtruck/core'import { menuTheme } from './components/Menu'const theme = extendTheme({components: {Menu: menuTheme,},})export default theme
This is a crucial step to make sure that any changes we make to the menu theme are applied.
Adding a custom size#
Let's assume we want to include an extra large menu size. Here's how we can do that:
import { menuAnatomy } from '@chakra-ui/anatomy'import { createMultiStyleConfigHelpers, defineStyle } from '@fluidtruck/core'const { definePartsStyle, defineMultiStyleConfig } =createMultiStyleConfigHelpers(menuAnatomy.keys)// define custom stylesconst lg = defineStyle({fontSize: 'md',my: '1',})const xl = defineStyle({fontSize: 'lg',px: '4',py: '2',})// define custom sizesconst sizes = {// apply custom styles to partsxl: definePartsStyle({ button: xl, item: xl, groupTitle: lg, command: xl }),}// export the sizes in the component themeexport const menuTheme = defineMultiStyleConfig({ sizes })// now we can use the new `xl` size<Menu size="xl" ... />
Every time you add anything new to the theme, you need to run the CLI command to get proper autocomplete in your IDE. You can learn more about the CLI tool here.
Adding a custom variant#
Let's assume we want to include some custom variants to create a pill-shaped menu bar. Here's how we can do that:
import { menuAnatomy } from '@chakra-ui/anatomy'import { createMultiStyleConfigHelpers, defineStyle } from '@fluidtruck/core'const { definePartsStyle, defineMultiStyleConfig } =createMultiStyleConfigHelpers(menuAnatomy.keys)// define custom variantsconst variants = {roundLeft: {button: {borderLeftRadius: 'full',pl: '6',},},roundRight: {button: {borderRightRadius: 'full',pr: '6',},},}// export the custom variants in the component themeexport const menuTheme = defineMultiStyleConfig({ variants })// now we can use the new `roundLeft` and `roundRight` variants<Menu variant="roundLeft" ... /><Menu variant="roundRight" ... />
Changing the default properties#
Let's assume we want to change the default size and variant of every menu in our app. Here's how we can do that:
import { menuAnatomy } from '@chakra-ui/anatomy'import { createMultiStyleConfigHelpers, defineStyle } from '@fluidtruck/core'const { definePartsStyle, defineMultiStyleConfig } =createMultiStyleConfigHelpers(menuAnatomy.keys)// define which sizes and variants are applied by defaultconst defaultProps = {// in this example, we will only set a default sizesize: 'xl',}// export the default properties in the component themeexport const menuTheme = defineMultiStyleConfig({ defaultProps })