Menu

A <role-menu> is intended to behave like a system menu. Menus can be used as submenus within a <role-menu-item>.

Menus follow the APG recommendation of “focus follows hover”, they also implement “safe triangles”.

Examples

API Reference

Imports

Script
HTML 
<!-- Auto registers as <role-menu> -->
<script type="module" src="https://cdn.jsdelivr.net/npm/role-components/exports/components/menu/menu-register.js"></script>
CDN
HTML 
<script type="module">
  // Auto registers as <role-menu>
  import "https://cdn.jsdelivr.net/npm/role-components/exports/components/menu/menu-register.js"

  // Manual Register
  import RoleMenu from "https://cdn.jsdelivr.net/npm/role-components/exports/components/menu/menu.js"
  RoleMenu.define()
  // => Registers as <role-menu>
</script>
Bundler
JavaScript 
// Auto registers as <role-menu>
import "role-components/exports/components/menu/menu-register.js"

// Manual Register
import RoleMenu "role-components/exports/components/menu/menu.js"
RoleMenu.define()
// => Registers as <role-menu>

Slots

Name Description

The default slot.
trigger

the text to go within the button
trigger-icon

the icon to indicate either the submenu or menu

Attributes

Name Description Reflects Type Default
[Attribute + Property]
placement

The preferred placement of the popover. Note that the actual placement will vary as configured to keep the panel inside of the viewport.

 'top' | 'top-start' | 'top-end' | 'bottom' | 'bottom-start' | 'bottom-end' | 'right' | 'right-start' | 'right-end' | 'left' | 'left-start' | 'left-end'
-
[Attribute + Property]
current-placement

The currentPlacement property / current-placement attribute are where Floating UI actually positions the popup.

 'top' | 'top-start' | 'top-end' | 'bottom' | 'bottom-start' | 'bottom-end' | 'right' | 'right-start' | 'right-end' | 'left' | 'left-start' | 'left-end' | null
-
[Attribute + Property]
strategy

Determines how the popover is positioned. Because you native “popover” API uses a fixed strategy, we use it as the default.

 Strategy
-
[Attribute + Property]
distance

The distance in pixels from which to offset along the “main axis”. Usually its equivalent to offsetY

 number
-
[Attribute + Property]
skidding

The distance in pixels from which to offset along the “cross axis”. Usually its equivalent to offsetX.

 number
-
[Attribute + Property]
arrow

Attaches an arrow to the popover. The arrow’s size and color can be customized using the --arrow-size and --background-color custom properties. For additional customizations, you can also target the arrow using ::part(arrow) in your stylesheet.

 boolean
-
[Attribute + Property]
arrow-placement

The placement of the arrow. The default is anchor, which will align the arrow as close to the center of the anchor as possible, considering available space and arrow-padding. A value of start, end, or center will align the arrow to the start, end, or center of the popover instead.

 'start' | 'end' | 'center' | 'anchor'
-
[Attribute + Property]
arrow-padding

The amount of padding between the arrow and the edges of the popover. If the popover has a border-radius, for example, this will prevent it from overflowing the corners.

 number
-
[Attribute + Property]
flip

When set, placement of the popover will flip to the opposite site to keep it in view. You can use flipFallbackPlacements to further configure how the fallback placement is determined.

 boolean
-
[Attribute + Property]
flip-fallback-placements

If the preferred placement doesn’t fit, popover will be tested in these fallback placements until one fits. Must be a string of any number of placements separated by a space, e.g. “top bottom left”. If no placement fits, the flip fallback strategy will be used instead.

 string
-
[Attribute + Property]
flip-fallback-strategy

When neither the preferred placement nor the fallback placements fit, this value will be used to determine whether the popover should be positioned using the best available fit based on available space or as it was initially preferred.

 'best-fit' | 'initial'
-
[Attribute + Property]
flip-padding

The amount of padding, in pixels, to exceed before the flip behavior will occur.

 number
-
[Attribute + Property]
shift

Moves the popover along the axis to keep it in view when clipped.

 boolean
-
[Attribute + Property]
shift-padding

The amount of padding, in pixels, to exceed before the shift behavior will occur.

 number
-
[Attribute + Property]
auto-size

When set, this will cause the popover to automatically resize itself to prevent it from overflowing.

 null | 'horizontal' | 'vertical' | 'both'
-
[Attribute + Property]
sync

Syncs the popover’s width or height to that of the anchor element.

 null | 'width' | 'height' | 'both'
-
[Attribute + Property]
auto-size-padding

The amount of padding, in pixels, to exceed before the auto-size behavior will occur.

 number
-
[Attribute + Property]
hover-bridge

When a gap exists between the anchor and the popover element, this option will add a “hover bridge” that fills the gap using an invisible element. This makes listening for events such as mouseenter and mouseleave more sane because the pointer never technically leaves the element. The hover bridge will only be drawn when the popover is active.

 boolean
-

Events

Name Description
role-menu-item-selected

Fires when a menu item is selected and will close the menu. Called event.preventDefault() to stop this behavior.

Functions

Name Description Parameters
handleMenuItemSelected()
-
 e: RoleMenuItemSelectedEvent
handleOutsideClick()
-
 e: Event
handleKeydown()
-
 e: KeyboardEvent
focusAtIndex()
-
 index: number
focus()
-
 options: FocusOptions
focusTrigger()
-
 options: FocusOptions
focusMenuItem()
-
 menuItem: default
getOrAssignId()

Assign a random UUID with a prefix if no id is found. Will return the “id” of the element if its already assigned.

 prefix: string, force: boolean
getTextDirection()
-
-
debounce()
-
 callback: (...args: any[]) => any, options: { key: any, wait: number }
setAria()
-
 key: T, value: ARIAMixin[T]

Parts

Name Description
base

The component’s base wrapper.
trigger

the button that triggers the menu or submenu.
anchored-region

The anchored region element
popover

the popover within the anchored region
popover--active

if the popover is active
popover--fixed

if the popover is fixed
popover--has-arrow

if the popover has an arrow
arrow

the arrow element
hover-bridge

the hover bridge element
hover-bridge--visible

if the hover bridge is visible
Previous Page Listbox Next Page Menu Item