Element: <oj-c-menu-button>

CORE PACK

Oracle® JavaScript Extension Toolkit (JET)
18.0.0
G12199-01

Since:
  • 16.0.0
Module:
  • menu-button

Note: This component supersedes the following components: <oj-menu-button>, <oj-menu-select-many>. Migration info available at preceding links.

QuickNav

Slots

Attributes

Events

Methods

Type Definitions

Other Topics


Description: A menu button launches a menu when clicked. 

<oj-c-menu-button label="Copy" items="[[items]]">
</oj-c-menu-button>

Touch End User Information

Keyboard End User Information

Target Key Action
Menu Button Enter or Space or Down Arrow Invoke the Button menu.

Accessibility

For accessibility, the label and suffix are used as the accessible aria label. This is required as persistent menu buttons or suffixes modify the label depending on the last menu item selection.

Disabled content: JET supports an accessible luminosity contrast ratio, as specified in WCAG 2.0 - Section 1.4.3 "Contrast", in the themes that are accessible. (See the "Theming" chapter of the JET Developer Guide for more information on which themes are accessible.) Note that Section 1.4.3 says that text or images of text that are part of an inactive user interface component have no contrast requirement. Because disabled content may not meet the minimum contrast ratio required of enabled content, it cannot be used to convey meaningful information.


Usage

Signature:

interface CMenuButtonElement

Typescript Import Format
//To typecheck the element APIs, import as below.
import { CMenuButtonElement } from "oj-c/menu-button";

//For the transpiled javascript to load the element's module, import as below
import "oj-c/menu-button";

For additional information visit:

Note: Application logic should not interact with the component's properties or invoke its methods until the BusyContext indicates that the component is ready for interaction.


Slots

JET components that allow child content support slots. Please see the slots section of the JET component overview doc for more information on allowed slot content and slot types.

endIcon

The endIcon slot is the button's end icon. The oj-c-menu-button element accepts DOM nodes as children with the endIcon slot.

startIcon

The startIcon slot is the button's start icon. The oj-c-menu-button element accepts DOM nodes as children with the startIcon slot.

Attributes

chroming :"ghost"|"borderless"|"outlined"|"solid"

Indicates in what states the button has chromings in background and border.
Supported Values:
Value Description
borderless Borderless buttons are a more prominent variation. Borderless buttons are useful for supplemental actions that require minimal emphasis.
ghost Ghost buttons are the least prominent variation. Ghost buttons are useful for performing low-priority tasks, such as manipulating the UI.
outlined Outlined buttons are salient, but lighter weight than solid buttons. Outlined buttons are useful for secondary actions.
solid Solid buttons stand out, and direct the user's attention to the most important actions in the UI.
Default Value:
  • "outlined"
Names
Item Name
Property chroming
Property change event chromingChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-chroming-changed

disabled :boolean

Specifies that the button element should be disabled.
Default Value:
  • false
Names
Item Name
Property disabled
Property change event disabledChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-disabled-changed

display :"all"|"icons"|"label"

Display just the label, the icons, or all. Label is used as tooltip and should be set in all cases.
Supported Values:
Value Description
all Display both the label and icons.
icons Display only the icons.
label Display only the text label.
Default Value:
  • "all"
Names
Item Name
Property display
Property change event displayChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-display-changed

items :Array.<(oj-c.MenuButton.MenuSeparator|oj-c.MenuButton.MenuItem|oj-c.MenuButton.MenuSubMenu|oj-c.MenuButton.MenuSelectSingle|oj-c.MenuButton.MenuSelectMultiple)>

Items describe the menu items rendered by the menu button.
Default Value:
  • []
Names
Item Name
Property items
Property change event itemsChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-items-changed

label* :string

Text to show in the button.
Default Value:
  • ""
Names
Item Name
Property label
Property change event labelChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-label*-changed

selection :Readonly<Record<string, MenuSelection>>

An array containing key/value objects for menu selection groups.
Supports writeback:
  • true
Names
Item Name
Property selection
Property change event selectionChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-selection-changed

size :"xs"|"sm"|"md"|"lg"

Size of button
Supported Values:
Value Description
lg Display a large button.
md Display a default size button.
sm Display a small button.
xs Display an extra small button. Only supported for component developers with ghost chroming in icon display mode.
Default Value:
  • "md"
Names
Item Name
Property size
Property change event sizeChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-size-changed

suffix :string

Suffix appended to menu label to indicate last selection.
Names
Item Name
Property suffix
Property change event suffixChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-suffix-changed

tooltip :string

Text to show in the tooltip. This overrides the default tooltip that renders the label when in icon mode.
Names
Item Name
Property tooltip
Property change event tooltipChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-tooltip-changed

width :(number|string)

Specifies that the button style width
Names
Item Name
Property width
Property change event widthChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-width-changed

Events

ojMenuAction

Triggered when a menu item is clicked, whether by keyboard, mouse, or touch events. Detail indicates which menu item was clicked.
Properties:

All of the event payloads listed below can be found under event.detail. See Events and Listeners for additional information.

Name Type
key string

ojMenuSelection

Triggered when a menu selection group item is clicked, whether by keyboard, mouse, or touch events. Detail indicates new selection value for group.
Properties:

All of the event payloads listed below can be found under event.detail. See Events and Listeners for additional information.

Name Type
menuSelectionGroupKey string
value T

Methods

blur : {void}

Returns:
Type
void

click : {void}

Returns:
Type
void

focus : {void}

Returns:
Type
void

getProperty(property) : {any}

Retrieves the value of a property or a subproperty.
Parameters:
Name Type Description
property The property name to get. Supports dot notation for subproperty access.
Returns:
Type
any

setProperties(properties) : {void}

Performs a batch set of properties.
Parameters:
Name Type Description
properties An object containing the property and value pairs to set.
Returns:
Type
void

setProperty(property, value) : {void}

Sets a property or a single subproperty for complex properties and notifies the component of the change, triggering a corresponding event.
Parameters:
Name Type Description
property The property name to set. Supports dot notation for subproperty access.
value The new value to set the property to.
Returns:
Type
void

Type Definitions

Specifies a standard menu item.
Properties:
Name Type Argument Description
disabled boolean <optional>
 Specifies if the menu item is disabled (enabled by default).
endIcon { type?: 'class'; class: string; } | { type: 'img'; src: string; } <optional>
 Optional icon to render at the end of the menu item.
key string A unique key associated with the menu item.
label string The menu item label.
onAction function <optional>
 Optional callback function associated with the menu item.
startIcon { type?: 'class'; class: string; } | { type: 'img'; src: string; } <optional>
 Optional icon to render at the start of the menu item.
type "item" <optional>
 Specifies a standard menu item.
variant "standard" | "destructive" <optional>
 Specifies the menu item behavior.
Specifies a selectable item in a menu item.
Properties:
Name Type Argument Description
disabled boolean <optional>
 Specifies if the selectable item is disabled (enabled by default).
endIcon { type?: 'class'; class: string; } | { type: 'img'; src: string; } <optional>
 Optional icon to render at the end of the selectable item.
label string The selectable item label.
value string The value associated with the selectable item.
Specifies a menu item representing a select multiple.
Properties:
Name Type Argument Description
items Array.<oj-c.MenuButton.MenuSelectItem> <optional>
 Specifies the array of select items that make up the select multiple.
key string A unique key associated with the select multiple.
type "selectmultiple" Specifies a select multiple menu item.
Specifies a menu item representing a select single.
Properties:
Name Type Argument Description
items Array.<oj-c.MenuButton.MenuSelectItem> <optional>
 Specifies the array of select items that make up the select single.
key string A unique key associated with the select single.
type "selectsingle" Specifies a select single menu item.
Specifies a menu separator: { type: "separator" }.
Properties:
Name Type Description
type separator | divider
Deprecated:
Since Value Description
17.0.0 divider Use 'separator' instead.
"separator" 		Specifies a separator menu item.
Specifies a menu item representing a submenu.
Properties:
Name Type Argument Description
disabled boolean <optional>
 Specifies if the submenu is disabled (enabled by default).
items Array<oj-c.MenuButton.MenuSeparator | oj-c.MenuButton.MenuItem | oj-c.MenuButton.MenuSubMenu | oj-c.MenuButton.MenuSelectSingle | oj-c.MenuButton.MenuSelectMultiple> <optional>
 Specifies the array of menu items that make up the submenu.
key string <optional>
 A unique key associated with the submenu menu item.
label string <optional>
 The submenu label.
startIcon string <optional>
 Optional icon to render at the start of the submenu.
type "submenu" Specifies a submenu menu item.