Menu is a top-level component that contains menu items and other lower level submenus.
Working with a MenuButton or a compatible button component, Menu manages states which controls the display of its contents and maintains focus among its descendants.
It should be able to serve the majority of use cases. If you need more controls on how and when a menu is open or closed, you might use a ControlledMenu.
Props
Name
Type
Default
Description
align
string
'start'
Can be 'start', 'center', or 'end'.
It sets alignment of menu with anchor element.
aria-label
string
Sets aria-label attribute on the menu DOM element.
If not provided, one will be generated from the string content of menu button, or the default 'Menu'.
arrow
boolean
Set true to display an arrow pointing to its anchor element.
arrowProps
object
Properties of this object are spread to the menu arrow DOM element.
arrowProps.className
string | function
A string that will be appended to the class of menu arrow DOM element.
When a function is provided, it will be called by passing an object with the following properties and should return a CSS class name.
dir: string computed direction in which the menu expands. Can be 'left', 'right', 'top', or 'bottom'.
boundingBoxPadding
string
Specify bounding box padding in pixels. Use a syntax similar to the CSS padding property but sizing units are discarded.
boundingBoxRef
object
A ref object attached to a DOM element within which menu will be positioned. If not provided, the nearest ancestor which has CSS overflow set to a value other than 'visible' or the browser viewport will serve as the bounding box.
Supports ref created by React.createRef or useRef Hook, or an object of { current: { getBoundingClientRect(): DOMRect } }. Doesn't support callback ref.
children
node | function
Menu items underneath the menu, or a function that returns them. The function will be called by passing an object with the following properties:
state: string indicates the state of menu. Can be 'opening', 'open', 'closing', 'closed'.
align: string alignment of menu with anchor element. Can be 'start', 'center', or 'end'.
dir: string computed direction in which the menu expands. Can be 'left', 'right', 'top', or 'bottom'.
containerProps
object
Properties of this object are spread to the root DOM element containing the menu.
direction
string
'bottom' or 'right' for SubMenu
Can be 'left', 'right', 'top', or 'bottom'.
It sets direction in which menu expands against anchor element.
focusProps
object
Properties of this object are spread to a DOM element which captures focus for the menu.
gap
number
0
Add a gap (gutter) between menu and its anchor element. The value (in pixels) can be negative.
initialMounted
boolean
By default menu isn't mounted into DOM until it's opened for the first time. Setting the prop to true will change this behaviour, which also enables menu and its items to be server rendered.
instanceRef
React.Ref <MenuInstance>
A ref which attaches to menu component and provides the follow methods:
openMenu: (position?: 'first' | 'last' | number, alwaysUpdate?: boolean) => void open menu, optional request which menu item will be hovered.
closeMenu: () => void close menu
menuButton
element | function
Can be a MenuButton, a button element, or a React component.
It also accepts a function that returns one of the above. The function will be called by passing an object with the following properties:
open: bool indicates if the menu is open.
If a React component is provided, it needs to implement the following contracts:
Accepts a ref prop that is forwarded to the element to which menu will be positioned. The element should be able to receive focus.
Accepts onClick and onKeyDown event props.
Please note MenuButton has one additional benefit that it has managed aria-haspopup and aria-expanded attributes. When using a button element or your own React component, it's your job to set these aria attributes if you need correct accessibility support.
menuClassName
string | function
A string that will be appended to the class of menu DOM element.
When a function is provided, it will be called by passing an object with the following properties and should return a CSS class name.
state: string indicates the state of menu. Can be 'opening', 'open', 'closing', 'closed'.
align: string alignment of menu with anchor element. Can be 'start', 'center', or 'end'.
dir: string computed direction in which the menu expands. Can be 'left', 'right', 'top', or 'bottom'.
menuStyle
CSSProperties
This value is forwarded to the style prop of menu DOM element.
onItemClick
function
Event fired when descendent menu items are clicked.
Event object properties:
value: any the value prop passed to the MenuItem being clicked. It's useful for helping identify which menu item is clicked.
key: string indicates the key if click is triggered by keyboard. Can be 'Enter' or ' '(Space).
checked: bool indicates if the menu item is checked, only for MenuItemtype="checkbox".
name: string the name prop passed to the MenuRadioGroup when the menu item is in a radio group.
keepOpen: bool set this property on event object to control whether to keep menu open after menu item is activated. Leaving it undefined will behave in accordance with WAI-ARIA Authoring Practices. See a CodeSandbox example for its usage.
stopPropagation: bool setting this property on event object to true will skip onItemClick event on root menu component.
syntheticEvent: MouseEvent | KeyboardEvent DOM event object (React synthetic event)
onMenuChange
function
Event fired when menu states have changed.
Event object properties:
open: bool indicates if the menu is open.
overflow
string
'visible'
Can be 'visible', 'auto', or 'hidden'.
It makes the menu list scrollable or hidden when there is not enough viewport space to display all menu items. The value is similar to the CSS overflow property.
Menu is a top-level component that contains menu items and other lower level submenus.
Working with a MenuButton or a compatible button component, Menu manages states which controls the display of its contents and maintains focus among its descendants.
It should be able to serve the majority of use cases. If you need more controls on how and when a menu is open or closed, you might use a ControlledMenu.
Props
Name
Type
Default
Description
align
string
'start'
Can be 'start', 'center', or 'end'.
It sets alignment of menu with anchor element.
aria-label
string
Sets aria-label attribute on the menu DOM element.
If not provided, one will be generated from the string content of menu button, or the default 'Menu'.
arrow
boolean
Set true to display an arrow pointing to its anchor element.
arrowProps
object
Properties of this object are spread to the menu arrow DOM element.
arrowProps.className
string | function
A string that will be appended to the class of menu arrow DOM element.
When a function is provided, it will be called by passing an object with the following properties and should return a CSS class name.
dir: string computed direction in which the menu expands. Can be 'left', 'right', 'top', or 'bottom'.
boundingBoxPadding
string
Specify bounding box padding in pixels. Use a syntax similar to the CSS padding property but sizing units are discarded.
boundingBoxRef
object
A ref object attached to a DOM element within which menu will be positioned. If not provided, the nearest ancestor which has CSS overflow set to a value other than 'visible' or the browser viewport will serve as the bounding box.
Supports ref created by React.createRef or useRef Hook, or an object of { current: { getBoundingClientRect(): DOMRect } }. Doesn't support callback ref.
children
node | function
Menu items underneath the menu, or a function that returns them. The function will be called by passing an object with the following properties:
state: string indicates the state of menu. Can be 'opening', 'open', 'closing', 'closed'.
align: string alignment of menu with anchor element. Can be 'start', 'center', or 'end'.
dir: string computed direction in which the menu expands. Can be 'left', 'right', 'top', or 'bottom'.
containerProps
object
Properties of this object are spread to the root DOM element containing the menu.
direction
string
'bottom' or 'right' for SubMenu
Can be 'left', 'right', 'top', or 'bottom'.
It sets direction in which menu expands against anchor element.
focusProps
object
Properties of this object are spread to a DOM element which captures focus for the menu.
gap
number
0
Add a gap (gutter) between menu and its anchor element. The value (in pixels) can be negative.
initialMounted
boolean
By default menu isn't mounted into DOM until it's opened for the first time. Setting the prop to true will change this behaviour, which also enables menu and its items to be server rendered.
instanceRef
React.Ref <MenuInstance>
A ref which attaches to menu component and provides the follow methods:
openMenu: (position?: 'first' | 'last' | number, alwaysUpdate?: boolean) => void open menu, optional request which menu item will be hovered.
closeMenu: () => void close menu
menuButton
element | function
Can be a MenuButton, a button element, or a React component.
It also accepts a function that returns one of the above. The function will be called by passing an object with the following properties:
open: bool indicates if the menu is open.
If a React component is provided, it needs to implement the following contracts:
Accepts a ref prop that is forwarded to the element to which menu will be positioned. The element should be able to receive focus.
Accepts onClick and onKeyDown event props.
Please note MenuButton has one additional benefit that it has managed aria-haspopup and aria-expanded attributes. When using a button element or your own React component, it's your job to set these aria attributes if you need correct accessibility support.
menuClassName
string | function
A string that will be appended to the class of menu DOM element.
When a function is provided, it will be called by passing an object with the following properties and should return a CSS class name.
state: string indicates the state of menu. Can be 'opening', 'open', 'closing', 'closed'.
align: string alignment of menu with anchor element. Can be 'start', 'center', or 'end'.
dir: string computed direction in which the menu expands. Can be 'left', 'right', 'top', or 'bottom'.
menuStyle
CSSProperties
This value is forwarded to the style prop of menu DOM element.
onItemClick
function
Event fired when descendent menu items are clicked.
Event object properties:
value: any the value prop passed to the MenuItem being clicked. It's useful for helping identify which menu item is clicked.
key: string indicates the key if click is triggered by keyboard. Can be 'Enter' or ' '(Space).
checked: bool indicates if the menu item is checked, only for MenuItemtype="checkbox".
name: string the name prop passed to the MenuRadioGroup when the menu item is in a radio group.
keepOpen: bool set this property on event object to control whether to keep menu open after menu item is activated. Leaving it undefined will behave in accordance with WAI-ARIA Authoring Practices. See a CodeSandbox example for its usage.
stopPropagation: bool setting this property on event object to true will skip onItemClick event on root menu component.
syntheticEvent: MouseEvent | KeyboardEvent DOM event object (React synthetic event)
onMenuChange
function
Event fired when menu states have changed.
Event object properties:
open: bool indicates if the menu is open.
overflow
string
'visible'
Can be 'visible', 'auto', or 'hidden'.
It makes the menu list scrollable or hidden when there is not enough viewport space to display all menu items. The value is similar to the CSS overflow property.
React-Menu implements WAI-ARIA roles, states, and properties which adhere to the WAI-ARIA Authoring Practices. For more details, please refer to the website.
React-Menu implements WAI-ARIA roles, states, and properties which adhere to the WAI-ARIA Authoring Practices. For more details, please refer to the website.
React-Menu supports the following keyboard interactions:
Menu
Return activates a menu item and closes the menu.
Space activates a menu item and closes the menu; for radio and checkbox item, activates the menu item without closing the menu.
Down Arrow moves focus to the next item, wrapping from the last to the first.
Up Arrow moves focus to the previous item, wrapping from the first to the last.
Home moves focus to the first item.
End moves focus to the last item.
Esc Closes a menu and move focus to its associated menu button.
Left Arrow Closes a submenu if it is open.
Return | Space | Right Arrow When focus is in a submenu item, opens the submenu, and moves focus to the first menu item.
MenuButton
Return | Space | Down Arrow opens the associated menu and moves focus to the first menu item.
Up Arrow opens the associated menu and moves focus to the last menu item.
\ No newline at end of file
diff --git a/index.html b/index.html
index 29f827f7..9f479d78 100644
--- a/index.html
+++ b/index.html
@@ -1,4 +1,4 @@
-React menu library - szhsin/react-menu
In some use cases you may need to access a menu's state and control how the menu is open or closed. This can be implemented using a ControlledMenu.
You need to provide at least a state prop, and a ref of an element to which menu will be positioned. You also need to update state in response to the onClose event.
You can optionally leverage a useClick hook which helps create a similar toggle menu experience to the Menu component.
Cut
Copy
Paste
import { useRef, useState } from 'react';
+</Menu>
In some use cases you may need to access a menu's state and control how the menu is open or closed. This can be implemented using a ControlledMenu.
You need to provide at least a state prop, and a ref of an element to which menu will be positioned. You also need to update state in response to the onClose event.
You can optionally leverage a useClick hook which helps create a similar toggle menu experience to the Menu component.
\ No newline at end of file
diff --git a/style-guide.html b/style-guide.html
index 9b03fbdc..6c4dcdcc 100644
--- a/style-guide.html
+++ b/style-guide.html
@@ -1,3 +1,3 @@
-React menu library - szhsin/react-menu
React-Menu comes with the following CSS files in the dist folder:
File
Description
core.css
Includes minimal styles (arrow, reset). This can be a starting point for customising styles.
You may import this file or copy the CSS into your own stylesheets or CSS-in-JS solution, and optionally remove styles you don't use (e.g. the arrows).
index.css
Default styles.
theme-dark.css
Includes dark theme styles, working in conjunction with index.css.
style-utils helps you write CSS selectors more easily with CSS-in-JS. Using it is optional but highly recommended. There are some examples demonstrating its usage.
React-Menu has a default z-index of 100 for positioned menu. If this value is not appropriate for your app, you could adjust it by overriding the .szh-menu selector.
E.g., set z-index to 1000:
.szh-menu {
+React menu library - szhsin/react-menu
React-Menu comes with the following CSS files in the dist folder:
File
Description
core.css
Includes minimal styles (arrow, reset). This can be a starting point for customising styles.
You may import this file or copy the CSS into your own stylesheets or CSS-in-JS solution, and optionally remove styles you don't use (e.g. the arrows).
index.css
Default styles.
theme-dark.css
Includes dark theme styles, working in conjunction with index.css.
style-utils helps you write CSS selectors more easily with CSS-in-JS. Using it is optional but highly recommended. There are some examples demonstrating its usage.
React-Menu has a default z-index of 100 for positioned menu. If this value is not appropriate for your app, you could adjust it by overriding the .szh-menu selector.