MenuButton | Codex
Edit Configuration
View Phab Ticket
Contact Owner
Turn Instrument Off
Delete Instrument
Edit
Share
Delete
Keyboard shortcuts
Leave feedback
Read the user guide
Keyboard shortcuts
Leave feedback
Read the user guide
Function call
Literal String
Reference
Edit Configuration
View Phab Ticket
Contact Owner
Turn Instrument Off
Delete Instrument
Skip to content
MenuButton
The MenuButton component is a
Button
that, when pressed toggles the display of a
with actions.
Name
Value
Props
action
default
progressive
destructive
weight
normal
primary
quiet
disabled
Slots
default
View
Reading direction
Left to right (LTR)
Right to left (RTL)
Overview
When to use MenuButton
Use the MenuButton component when the space is limited and you need to provide users with a set of related actions or options within a single button.
Avoid using MenuButton when there are only one or two actions to display. In that case, consider using separate buttons instead. Additionally, do not use MenuButton if the actions are essential and require immediate visibility without additional interaction.
The items within the Menu are meant to be actions. For a menu of selectable options, use
Select
About MenuButton
MenuButton includes the following elements.
Button
A single button to display the Menu. It can include an icon, a text label, or both.
A list of related actions. The Menu can be placed in a variety of positions relative to the button.
Make MenuItems more easily recognizable by including clear and relevant icons.
Don't use thumbnails within MenuItems, as they could make the Menu excessively large.
MenuItems can represent two types of actions:
Standard actions
Neutral actions such as "Edit" or "Share".
Destructive actions
Actions with potentially negative or irreversible impact, such as "Delete".
Examples
Basic usage
The Button that displays the Menu can be customized with text, an Icon, or both.
NPM
MediaWiki
vue
template
cdx-menu-button
v-model:selected
selection
:menu-items
menuItems
More options
cdx-menu-button
template
script
import
{ defineComponent, ref }
from
vue
import
{ CdxMenuButton }
from
@wikimedia/codex
const
menuItems
{ label
Edit
, value
edit
},
{ label
, value
},
{ label
, value
, disabled
true
},
{ label
Share
, value
share
},
{ label
Delete
, value
delete
, action
destructive
];
export
default
defineComponent
( {
name
MenuButtonBasic
components
{ CdxMenuButton },
setup
() {
const
selection
ref
null
);
return
selection,
menuItems
};
} );
script
vue
template
cdx-menu-button
v-model:selected
selection
:menu-items
menuItems
More options
cdx-menu-button
template
script
const
{ defineComponent, ref }
require
vue
);
const
{ CdxMenuButton }
require
@wikimedia/codex
);
const
menuItems
{ label
Edit
, value
edit
},
{ label
, value
},
{ label
, value
, disabled
true
},
{ label
Share
, value
share
},
{ label
Delete
, value
delete
, action
destructive
];
module
exports
defineComponent
( {
name
MenuButtonBasic
components
{ CdxMenuButton },
setup
() {
const
selection
ref
null
);
return
selection,
menuItems
};
} );
script
Developer notes
MenuButton has two required props:
selected
and
menuItems
. The
selected
prop needs to be bound with
v-model
With icon
Use an icon with the button label when you need to convey meaning through both textual and visual elements. An icon can be added to either or both sides of the label.
NPM
MediaWiki
vue
template
cdx-menu-button
v-model:selected
selection
:menu-items
menuItems
cdx-icon
:icon
cdxIconHelp
/>
Help
cdx-menu-button
template
script
import
{ defineComponent, ref }
from
vue
import
{ CdxMenuButton, CdxIcon }
from
@wikimedia/codex
import
{ cdxIconHelp }
from
@wikimedia/codex-icons
const
menuItems
{ label
Keyboard shortcuts
, value
keyboard
},
{ label
Leave feedback
, value
feedback
},
{ label
Read the user guide
, value
read
];
export
default
defineComponent
( {
name
MenuButtonBasic
components
{ CdxMenuButton, CdxIcon },
setup
() {
const
selection
ref
null
);
return
selection,
menuItems,
cdxIconHelp
};
} );
script
vue
template
cdx-menu-button
v-model:selected
selection
:menu-items
menuItems
cdx-icon
:icon
cdxIconHelp
>cdx-icon
Help
cdx-menu-button
template
script
const
{ defineComponent, ref }
require
vue
);
const
{ CdxMenuButton, CdxIcon }
require
@wikimedia/codex
);
const
{ cdxIconHelp }
require
./icons.json
);
const
menuItems
{ label
Keyboard shortcuts
, value
keyboard
},
{ label
Leave feedback
, value
feedback
},
{ label
Read the user guide
, value
read
];
module
exports
defineComponent
( {
name
MenuButtonBasic
components
{ CdxMenuButton, CdxIcon },
setup
() {
const
selection
ref
null
);
return
selection,
menuItems,
cdxIconHelp
};
} );
script
Icon-only
To add an icon, insert the Icon component in the slot content. Refer to the
Icon
component and the
overview of icons
to learn more about using icons.
When using an icon-only Button, add an `aria-label` to provide a label to users of assistive technology.
NPM
MediaWiki
vue
template
cdx-menu-button
v-model:selected
selection
:menu-items
menuItems
aria-label
Help options
cdx-icon
:icon
cdxIconHelp
/>
cdx-menu-button
template
script
import
{ defineComponent, ref }
from
vue
import
{ CdxMenuButton, CdxIcon }
from
@wikimedia/codex
import
{ cdxIconHelp }
from
@wikimedia/codex-icons
const
menuItems
{ label
Keyboard shortcuts
, value
keyboard
},
{ label
Leave feedback
, value
feedback
},
{ label
Read the user guide
, value
read
];
export
default
defineComponent
( {
name
MenuButtonWithIconOnly
components
{ CdxMenuButton, CdxIcon },
setup
() {
const
selection
ref
null
);
return
selection,
menuItems,
cdxIconHelp
};
} );
script
vue
template
cdx-menu-button
v-model:selected
selection
:menu-items
menuItems
aria-label
Help options
cdx-icon
:icon
cdxIconHelp
>cdx-icon
cdx-menu-button
template
script
const
{ defineComponent, ref }
require
vue
);
const
{ CdxMenuButton, CdxIcon }
require
@wikimedia/codex
);
const
{ cdxIconHelp }
require
./icons.json
);
const
menuItems
{ label
Keyboard shortcuts
, value
keyboard
},
{ label
Leave feedback
, value
feedback
},
{ label
Read the user guide
, value
read
];
module
exports
defineComponent
( {
name
MenuButtonWithIconOnly
components
{ CdxMenuButton, CdxIcon },
setup
() {
const
selection
ref
null
);
return
selection,
menuItems,
cdxIconHelp
};
} );
script
MenuItems with icons
Refer to the
MenuItem
component to learn about all features available for
menuItems
NPM
MediaWiki
vue
template
cdx-menu-button
v-model:selected
selection
:menu-items
menuItems
aria-label
Change input type
cdx-icon
:icon
cdxIconEllipsis
/>
cdx-menu-button
template
script
import
{ defineComponent, ref }
from
vue
import
{ CdxMenuButton, CdxIcon }
from
@wikimedia/codex
import
{ cdxIconEllipsis, cdxIconFunction, cdxIconLiteral, cdxIconInstance }
from
@wikimedia/codex-icons
const
menuItems
{ label
Function call
, value
function call
, icon
cdxIconFunction },
{ label
Literal String
, value
literal string
, icon
cdxIconLiteral },
{ label
Reference
, value
reference
, icon
cdxIconInstance }
];
export
default
defineComponent
( {
name
MenuButtonAndMenuItemsWithIcons
components
{ CdxMenuButton, CdxIcon },
setup
() {
const
selection
ref
null
);
return
selection,
menuItems,
cdxIconEllipsis
};
} );
script
vue
template
cdx-menu-button
v-model:selected
selection
:menu-items
menuItems
aria-label
Change input type
cdx-icon
:icon
cdxIconEllipsis
>cdx-icon
cdx-menu-button
template
script
const
{ defineComponent, ref }
require
vue
);
const
{ CdxMenuButton, CdxIcon }
require
@wikimedia/codex
);
const
{ cdxIconEllipsis, cdxIconFunction, cdxIconLiteral, cdxIconInstance }
require
./icons.json
);
const
menuItems
{ label
Function call
, value
function call
, icon
cdxIconFunction },
{ label
Literal String
, value
literal string
, icon
cdxIconLiteral },
{ label
Reference
, value
reference
, icon
cdxIconInstance }
];
module
exports
defineComponent
( {
name
MenuButtonAndMenuItemsWithIcons
components
{ CdxMenuButton, CdxIcon },
setup
() {
const
selection
ref
null
);
return
selection,
menuItems,
cdxIconEllipsis
};
} );
script
Triggering actions
When the user selects a MenuItem, it can trigger an immediate action instead of (or in addition to) storing their choice as a persistent selection.
If an action is destructive, label it as such to inform users of its consequences.
Don't include more than one destructive action within the menu.
In this example, selecting a MenuItem causes a message to temporarily display.
NPM
MediaWiki
vue
template
cdx-menu-button
v-model:selected
selection
:menu-items
menuItems
aria-label
Choose an option
@update:selected
onSelect
cdx-icon
:icon
cdxIconEllipsis
/>
cdx-menu-button
cdx-message
v-if
isMessageVisible
type
notice
:auto-dismiss
true
:display-time
3000
:fade-in
true
{{ messageContent }}
cdx-message
template
script
import
{ defineComponent, ref }
from
vue
import
{ CdxMenuButton, CdxMessage, CdxIcon }
from
@wikimedia/codex
import
{ cdxIconEllipsis }
from
@wikimedia/codex-icons
const
isMessageVisible
ref
false
);
const
messageContent
ref
''
);
const
menuItems
{ label
Edit Configuration
, value
edit configuration
},
{ label
View Phab Ticket
, value
view phab ticket
},
{ label
Contact Owner
, value
contact owner
},
{ label
Turn Instrument Off
, value
turn instrument off
},
{ label
Delete Instrument
, value
delete instrument
, action
destructive
];
export
default
defineComponent
( {
name
MenuButtonSelection
components
{ CdxMenuButton, CdxMessage, CdxIcon },
setup
() {
const
selection
ref
null
);
function
onSelect
newSelection
) {
// Trigger a temporary message that shows the current selection.
messageContent.value
`You chose
${
newSelection
.`
isMessageVisible.value
true
setTimeout
( ()
=>
// Auto-dismiss the message.
isMessageVisible.value
false
},
3000
);
selection.value
null
return
selection,
menuItems,
isMessageVisible,
messageContent,
onSelect,
cdxIconEllipsis
};
} );
script
vue
template
cdx-menu-button
v-model:selected
selection
:menu-items
menuItems
aria-label
Choose an option
@update:selected
onSelect
cdx-icon
:icon
cdxIconEllipsis
>cdx-icon
cdx-menu-button
cdx-message
v-if
isMessageVisible
type
notice
:auto-dismiss
true
:display-time
3000
:fade-in
true
{{ messageContent }}
cdx-message
template
script
const
{ defineComponent, ref }
require
vue
);
const
{ CdxMenuButton, CdxMessage, CdxIcon }
require
@wikimedia/codex
);
const
{ cdxIconEllipsis }
require
./icons.json
);
const
isMessageVisible
ref
false
);
const
messageContent
ref
''
);
const
menuItems
{ label
Edit Configuration
, value
edit configuration
},
{ label
View Phab Ticket
, value
view phab ticket
},
{ label
Contact Owner
, value
contact owner
},
{ label
Turn Instrument Off
, value
turn instrument off
},
{ label
Delete Instrument
, value
delete instrument
, action
destructive
];
module
exports
defineComponent
( {
name
MenuButtonSelection
components
{ CdxMenuButton, CdxMessage, CdxIcon },
setup
() {
const
selection
ref
null
);
function
onSelect
newSelection
) {
// Trigger a temporary message that shows the current selection.
messageContent.value
`You chose
${
newSelection
.`
isMessageVisible.value
true
setTimeout
( ()
=>
// Auto-dismiss the message.
isMessageVisible.value
false
},
3000
);
selection.value
null
return
selection,
menuItems,
isMessageVisible,
messageContent,
onSelect,
cdxIconEllipsis
};
} );
script
Developer notes
In this example, the component listens for
@update:selected
events from the MenuButton component, handles the selection change with the
onSelect
method, displays a temporary message using the
Message
component, and resets the selection after a few seconds.
Other features
The MenuButton component has an internal Button and Menu. You can use the following features from those components in the MenuButton component:
Custom menu item display
Limited height with scrolling
Menu groups
MenuItem features
Button types
Technical implementation
Vue usage
Props
Prop name
Description
Type
Values
Default
selected
(required)
Value of the current selection.
This prop should be initialized to
null
(for single-select) or an empty array (for multi-select) rather than using a falsy value.
Must be bound with
v-model:selected
MenuItemValue
MenuItemValue
[]|null
menuItems
(required)
Menu items and/or menu group definitions.
Menu groups and individual menu items will be output in the order they appear here.
MenuButtonItemData
MenuGroupData
)[]
menuConfig
Configuration for various menu features. All properties default to false.
See the MenuConfig type.
MenuConfig
{}
action
The kind of action that will be taken on click.
ButtonAction
'default'
'progressive'
'destructive'
'default'
weight
Visual prominence of Button.
ButtonWeight
'normal'
'primary'
'quiet'
'quiet'
disabled
Whether the dropdown is disabled.
boolean
false
footer
Interactive footer item.
This is a special menu item which is pinned to the bottom of the menu. When scrolling is enabled within the menu, the footer item will always be visible at the bottom of the menu. When scrolling is not enabled, the footer item will simply appear as the last menu item.
The footer item is selectable, like other menu items.
MenuItemData
null
Events
Event name
Properties
Description
update:selected
selected
string|number
- The new selected value
When the selected value changes.
Slots
Name
Description
Bindings
default
MenuButton content
menu-item
Display of an individual item in the menu
menu-item
MenuItemData
- The current menu item
Keyboard navigation
Key
Function
Enter
If the focus is placed on the button, it opens and closes the menu. If the focus is placed on any of the options within the displayed menu, it activates that option.
Space
If the focus is placed on the button, it opens and closes the menu.
Down arrow
Up arrow
If the menu is displayed, it navigates through menu options.
Esc
It closes the menu when it is open.
Optionally, it moves the focus to the first option. Optionally, in a single-select listbox, selection may also move with focus. Supporting this key is strongly recommended for lists with more than five options.
End
Optionally, it moves the focus to the last option. Optionally, in a single-select listbox, selection may also move with focus. Supporting this key is strongly recommended for lists with more than five options.