grommet
docs
components

Menu

a control that opens a drop containing plain buttons

Storybook
CodeSandbox
Github

Props

a11yTitle

Custom label to be used by screen readers. When provided, an aria-label will be added to the element.

string
"a user friendly label for screen readers"

alignSelf

How to align along the cross axis when contained in a Box or along the column axis when contained in a Grid.

string
"start"
"center"
"end"
"stretch"

children

Menu can take in children as a function or node.

function

Function that will be called to render the visual representation. It will be passed a props object. The props passed are different depending on the menu open state. When the menu is closed, two props are passed: hover and focus. When the menu is open, all menu props are passed to this function. It should return a React element. Note: This function will be invoked on every mouse move when hovering.

(props) => <Box ...>{...}</Box>
node

Node is anything that can be rendered


<Box>
  <CaretNext />
  <Text>Open Me</Text>
</Box>

disabled

Whether the menu should be disabled.

boolean
true
false

dropAlign

Where to place the drop down.

object

The keys correspond to a side of the drop down. The values correspond to a side of the control. For instance, {left: 'left', top: 'bottom'} would align the left edges and the top of the drop down to the bottom of the control. At most one of left or right and one of top or bottom should be specified.


{
  top: "top" | "bottom",
  bottom: "top" | "bottom",
  right: "left" | "right",
  left: "left" | "right"
}
            
 { top: "top", left: "left" }

dropBackground

Background color when drop is active

string
"neutral-1"
object
{ color: "neutral-1", opacity: "medium" }
where opacity could be:
"weak"
"medium"
"strong"
true

dropProps

Any valid Drop prop.

object
{}

dropTarget

Target where the drop will be aligned to. This should be a React reference. Typically, this is not required as the drop will be aligned to the Menu itself by default.

object
ref.current

gridArea

The name of the area to place this inside a parent Grid.

string
"a parent grid area name"

icon

Indicates the icon shown as a control to open it.

boolean
true
false
node
<Icon />

items

Menu items to be placed inside the drop down. The object values can be any Button prop, for example: label, onClick, and href.

array[object]
 [{}, {}]

justifyContent

How to align the contents along the row axis.

string
"start"
"center"
"end"
"between"
"around"
"stretch"

label

Indicates the label shown as a control to open it.

string
"Actions"
node
<Box>...</Box>

margin

The amount of margin around the component.

string
"none"
"xxsmall"
"xsmall"
"small"
"medium"
"large"
"xlarge"
object

Can be specified to distinguish horizontal margin, vertical margin, and margin on a particular side.


{
    vertical: "...",
    horizontal: "...",
    top: "...",
    bottom: "...",
    left: "...",
    right: "..."
}

messages

Custom messages. Used for accessibility by screen readers. These values will be overridden if an a11yTitle is provided.

object

{
  openMenu: "Open Menu",
  closeMenu: "Close Menu"
}

open

Whether the state of the component should be open

boolean
true
false

size

The size of the menu.

string
"small"
"medium"
"large"
"xlarge"
"string"

React/DOM Properties

At its core, the Menu component is a regular <button> element. Thus, both DOM and React properties, methods, and events are accessible. To read up on all of the possible DOM attributes and types available for button elements, check out this MDN Web Documents page. To learn more about DOM events and methods, you can read more on the MDN Web Events documentation page.

Also, feel free to read about the types of React events available, or see how DOM attributes change in React. Working in tandem with Styled Components, you also have access to the as property.

Theme

global.colors.control

The default color to use for the icon.

string

A hex, name, or rgb value.

"brand"
object

An object with a color for dark and light modes.

{ dark: "accent-1", light: "brand" }