Overflow menu is used when additional options are available to the user and there is a space constraint.
Overflow menu
<!--
Copyright IBM Corp. 2016, 2018
This source code is licensed under the Apache-2.0 license found in the
LICENSE file in the root directory of this source tree.
-->
<div data-overflow-menu tabindex="0" aria-label="Overflow" class="bx--overflow-menu" role="button"
aria-haspopup="true" aria-expanded="false">
<svg aria-hidden="true" class="bx--overflow-menu__icon" width="3" height="15" viewBox="0 0 3 15">
<g fill-rule="evenodd">
<circle cx="1.5" cy="1.5" r="1.5" />
<circle cx="1.5" cy="7.5" r="1.5" />
<circle cx="1.5" cy="13.5" r="1.5" />
</g>
</svg>
<ul class="bx--overflow-menu-options" tabindex="-1" role="menu" aria-label="Overflow"
data-floating-menu-direction="bottom">
<li
class="bx--overflow-menu-options__option "
role="presentation" >
<button class="bx--overflow-menu-options__btn" role="menuitem" title="An example option that is really long to show what should be done to handle long text"
data-floating-menu-primary-focus >An example option that is really long to show what should be done to handle long text</button>
</li>
<li
class="bx--overflow-menu-options__option "
role="presentation" >
<button class="bx--overflow-menu-options__btn" role="menuitem" >Option 2</button>
</li>
<li
class="bx--overflow-menu-options__option "
role="presentation" >
<button class="bx--overflow-menu-options__btn" role="menuitem" >Option 3</button>
</li>
<li
class="bx--overflow-menu-options__option "
role="presentation" >
<button class="bx--overflow-menu-options__btn" role="menuitem" >Option 4</button>
</li>
<li
class="bx--overflow-menu-options__option bx--overflow-menu-options__option--disabled "
role="presentation" aria-disabled="true" >
<button class="bx--overflow-menu-options__btn" role="menuitem" tabindex="-1"
>Disabled</button>
</li>
<li
class="bx--overflow-menu-options__option bx--overflow-menu-options__option--danger "
role="presentation" >
<button class="bx--overflow-menu-options__btn" role="menuitem" >Danger option</button>
</li>
</ul>
</div>
<div data-overflow-menu tabindex="0" aria-label="Overflow" class="bx--overflow-menu" role="button"
aria-haspopup="true" aria-expanded="false">
<svg aria-hidden="true" class="bx--overflow-menu__icon" width="3" height="15" viewBox="0 0 3 15">
<g fill-rule="evenodd">
<circle cx="1.5" cy="1.5" r="1.5" />
<circle cx="1.5" cy="7.5" r="1.5" />
<circle cx="1.5" cy="13.5" r="1.5" />
</g>
</svg>
<ul class="bx--overflow-menu-options bx--overflow-menu--flip" tabindex="-1"
data-floating-menu-direction="bottom" role="menu" aria-label="Overflow">
<li
class="bx--overflow-menu-options__option "
role="presentation" >
<button class="bx--overflow-menu-options__btn" role="menuitem" title="An example option that is really long to show what should be done to handle long text"
data-floating-menu-primary-focus >An example option that is really long to show what should be done to handle long text</button>
</li>
<li
class="bx--overflow-menu-options__option "
role="presentation" >
<button class="bx--overflow-menu-options__btn" role="menuitem" >Option 2</button>
</li>
<li
class="bx--overflow-menu-options__option "
role="presentation" >
<button class="bx--overflow-menu-options__btn" role="menuitem" >Option 3</button>
</li>
<li
class="bx--overflow-menu-options__option "
role="presentation" >
<button class="bx--overflow-menu-options__btn" role="menuitem" >Option 4</button>
</li>
<li
class="bx--overflow-menu-options__option bx--overflow-menu-options__option--disabled "
role="presentation" aria-disabled="true" >
<button class="bx--overflow-menu-options__btn" role="menuitem" tabindex="-1"
>Disabled</button>
</li>
<li
class="bx--overflow-menu-options__option bx--overflow-menu-options__option--danger "
role="presentation" >
<button class="bx--overflow-menu-options__btn" role="menuitem" >Danger option</button>
</li>
</ul>
</div>
<div data-overflow-menu tabindex="0" aria-label="Overflow" class="bx--overflow-menu" role="button" aria-haspopup="true"
aria-expanded="false">
<svg aria-hidden="true" class="bx--overflow-menu__icon" width="3" height="15" viewBox="0 0 3 15">
<g fill-rule="evenodd">
<circle cx="1.5" cy="1.5" r="1.5" />
<circle cx="1.5" cy="7.5" r="1.5" />
<circle cx="1.5" cy="13.5" r="1.5" />
</g>
</svg>
<ul class="bx--overflow-menu-options bx--overflow-menu--flip" tabindex="-1" data-floating-menu-direction="bottom"
role="menu" aria-label="Overflow">
<li class="bx--overflow-menu-options__option"
role="presentation">
<a href="https://www.ibm.com" class="bx--overflow-menu-options__btn" role="menuitem" title="An example option that is really long to show what should be done to handle long text"
data-floating-menu-primary-focus>An example option that is really long to show what should be done to handle long text</a>
</li>
<li class="bx--overflow-menu-options__option"
role="presentation">
<a href="https://www.ibm.com" class="bx--overflow-menu-options__btn" role="menuitem"
>Option 2</a>
</li>
<li class="bx--overflow-menu-options__option"
role="presentation">
<a href="https://www.ibm.com" class="bx--overflow-menu-options__btn" role="menuitem"
>Option 3</a>
</li>
<li class="bx--overflow-menu-options__option"
role="presentation">
<a href="https://www.ibm.com" class="bx--overflow-menu-options__btn" role="menuitem"
>Option 4</a>
</li>
<li class="bx--overflow-menu-options__option bx--overflow-menu-options__option--disabled"
role="presentation">
<a href="https://www.ibm.com" class="bx--overflow-menu-options__btn" role="menuitem"
tabindex="-1" >Disabled</a>
</li>
<li class="bx--overflow-menu-options__option bx--overflow-menu-options__option--danger"
role="presentation">
<a href="https://www.ibm.com" class="bx--overflow-menu-options__btn" role="menuitem"
>Danger option</a>
</li>
</ul>
</div>
Documentation
SCSS
Modifiers
Use these modifiers with .bx--overflow-menu-options class.
Selector | Description |
---|---|
.bx--overflow-menu--flip |
Reverse the direction of the overflow menu. |
.bx--overflow-menu-options--open |
Displays the overflow menu options. |
JavaScript
Getting component class reference
ES2015
import { OverflowMenu } from 'carbon-components';
With pre-build bundle (carbon-components.min.js
)
var OverflowMenu = CarbonComponents.OverflowMenu;
Instantiating
// `#my-overflow-menu` is an element with `[data-overflow-menu]` attribute
OverflowMenu.create(document.getElementById('my-overflow-menu'));
Public Methods
Name | Params | Description |
---|---|---|
shouldStateBeChanged |
state : String |
Return true if the given state is different from the current state |
release |
Deletes the instance and removes document event listeners |
Options
Option | Default Selector | Description |
---|---|---|
selectorInit |
[data-overflow-menu] |
The CSS selector to find menu |
selectorPlacementScope |
body |
The CSS selector to find the element you wish the append the menu contents to |
selectorOptionMenu |
.bx--overflow-menu-options |
The CSS selector to find the contents of the menu |
objMenuOffset |
{ top: 3, left: 61 } |
An object containing the top and left offset values in px |
objMenuOffsetFlip |
{ top: 3, left: -61 } |
An object containing the top and left offset values in px for the "flipped" state |
Example - Changing menu position by 8 pixels vertically
// `#my-overflow-menu` is an element with `[data-overflow-menu]` attribute
OverflowMenu.create(document.getElementById('my-overflow-menu'), {
objMenuOffset(menuBody, direction) {
const { objMenuOffset: offset } = OverflowMenu.options;
const { top, left } = typeof offset !== 'function' ? offset : offset(menuBody, direction);
return {
top: top + 8,
left,
};
},
});
Events
Event Name | Description |
---|---|
'floating-menu-beingshown' | The custom event fired before the menu gets open. |
'floating-menu-shown' | The custom event fired after the menu gets open. |
'floating-menu-beinghidden' | The custom event fired before the menu gets closed. |
'floating-menu-hidden' | The custom event fired after the menu gets closed. |
Example - Preventing menu from being closed in a certain condition
document.addEventListener('floating-menu-beinghidden', function(evt) {
if (myApplication.shouldMenuKeptOpen(evt.target)) {
evt.preventDefault();
}
});
Example - Notifying events of all overflow menus being closed to an analytics library
document.addEventListener('floating-menu-hidden', function(evt) {
myAnalyticsLibrary.send({
action: 'Overflow menu closed',
id: evt.target.id,
});
});
HTML
By default, the menu body (ul.bx--overflow-menu-options
) goes right under <body>
. You can change the behavior by adding data-floating-menu-container
to one of the DOM ancestors of the root element (div[data-overflow-menu]
). For example, if you have HTML structure like below, the menu body will go under the second <div>
:
<body>
<div>
<div data-floating-menu-container>
<div>
<div data-overflow-menu class="bx--overflow-menu" ...>
...
<ul class="bx--overflow-menu-options" ...>
...
</ul>
</div>
</div>
</div>
</div>
</body>