Viewing: deepwiki.com

Relevant source files

This page documents the menu and selection component system in PatternFly Java, covering the core Menu and MenuItem components, their integration with MenuToggle through the MenuToggleMenu base class, and the specialized selection variants including SingleSelect, MultiSelect, SingleTypeahead, and MultiTypeahead.

For information about form input components, see Form and Input Components. For navigation components like breadcrumbs and jump links, see Navigation and Tabs. For the standalone MenuToggle component patterns, this page covers its integration with menus.

Component Architecture

The menu and selection system is built on a layered architecture where base menu functionality is extended by selection-specific wrappers:

Component Hierarchy Overview

Sources: components/src/main/java/org/patternfly/component/menu/Menu.java89-91 components/src/main/java/org/patternfly/component/menu/MenuToggleMenu.java68-76 components/src/main/java/org/patternfly/component/menu/SingleTypeahead.java38 components/src/main/java/org/patternfly/component/menu/MultiTypeahead.java41

The Menu class is the foundational component that displays a list of options or actions. It supports three menu types and five selection modes:

Menu Type	Purpose	Role Attribute
`menu`	Standard action menu	`menuitem`
`select`	Selection menu	`option`
`checkbox`	Checkbox selection	`menuitem` (on container)

Selection Mode	Behavior	Use Case
`click`	Single item marked as current	Navigation menus
`single`	Single item selected (radio behavior)	Single select
`group`	Single item per group	Grouped radio select
`multi`	Multiple items selected	Multi-select, checkboxes

The menu factory method requires both parameters:

Sources: components/src/main/java/org/patternfly/component/menu/Menu.java80-98 components/src/main/java/org/patternfly/component/menu/Menu.java294-309

A menu is composed hierarchically:

Menu Composition Structure

Sources: components/src/main/java/org/patternfly/component/menu/Menu.java144-184

MenuItem Types

MenuItem supports multiple item types, each with distinct behavior:

Type	Factory Method	Element Type	Use Case
`action`	`menuItem(id, text)`	`<button>`	Standard clickable action
`link`	`linkMenuItem(id, text, href)`	`<a>`	Navigation with href
`checkbox`	`checkboxMenuItem(id, text)`	`<label>` with `Checkbox`	Multi-select with checkbox
`async`	`asyncMenuItem(id, text, loadItems)`	`<button>`	Lazy-load nested items

The internal structure varies by type. For action/link items:

li (role=none)
   button/a (role=menuitem/option, tabindex=-1)
       span.pf-v5-c-menu__item-main
           span.pf-v5-c-menu__item-icon (optional)
           span.pf-v5-c-menu__item-text
           span.pf-v5-c-menu__item-select-icon (when selected)

For checkbox items:

li (role=none)
   label (tabindex=-1)
       span.pf-v5-c-menu__item-main
           span.pf-v5-c-menu__item-check
              Checkbox (standalone, tabindex=-1)
           span.pf-v5-c-menu__item-text

Sources: components/src/main/java/org/patternfly/component/menu/MenuItem.java106-144 components/src/main/java/org/patternfly/component/menu/MenuItem.java177-240

Selection Behavior

The Menu class manages selection state through the select() methods:

Selection behavior depends on SelectionMode:

click/single mode: Unselects all items, then marks the target item as current/selected
group mode: Unselects all items in the same group, then marks the target item
multi mode: Toggles individual items without affecting others

The internal methods makeCurrent() and markSelected() handle the visual state:

makeCurrent() sets aria-current (for click mode)
markSelected() sets aria-selected or toggles checkbox value (for single/group/multi modes)

Sources: components/src/main/java/org/patternfly/component/menu/Menu.java310-354 components/src/main/java/org/patternfly/component/menu/MenuItem.java526-553

Menu implements comprehensive keyboard navigation in the keyHandler() method:

Enter/Space: Activates the focused item
ArrowUp/ArrowDown: Navigates between menu items vertically
ArrowLeft/ArrowRight: Navigates between sibling actions (e.g., favorite button)

The navigation system:

Identifies navigable elements (visible <li> elements, excluding disabled/dividers)
Finds focusable elements within (<button>, <a>, <input>)
Manages tabIndex properties (0 for focused, -1 for others)
Wraps around at list boundaries

Sources: components/src/main/java/org/patternfly/component/menu/Menu.java490-620

MenuToggle Integration

MenuToggleMenu Base Class

MenuToggleMenu is an abstract base class that combines a MenuToggle with a Menu, managing their lifecycle and interaction through a Popper instance:

MenuToggleMenu Architecture

The attach() method performs critical initialization:

Sets menu visibility to false
Appends menu to document.body (prevents z-index/overflow issues)
Constructs Popper with modifiers (flip, hide, widths, etc.)
Registers MenuToggle click handler to expand/collapse
Binds window-level keyboard handler for Tab key

Sources: components/src/main/java/org/patternfly/component/menu/MenuToggleMenu.java96-144

Popper Configuration

The Popper is configured with specific modifiers and behaviors:

Modifier	Purpose
`eventListeners(false)`	Disables default Popper event listeners
`flip()`	Flips menu when it would overflow viewport
`hide()`	Hides menu when reference is hidden
`noOverflow()`	Prevents menu from overflowing boundaries
`widths()`	Syncs menu width with toggle width

The triggerActions parameter controls when the menu opens/closes (click, hover, focus, or stayOpen).

Sources: components/src/main/java/org/patternfly/component/menu/MenuToggleMenu.java110-130

Expandable Interface Implementation

MenuToggleMenu implements the Expandable interface, providing expand() and collapse() methods:

The expansion flow:

Shows the menu via Popper (with animation)
Updates ARIA expanded attribute
Fires toggle event handlers
If menu has async items (MenuList with pending status), loads them and fires loaded handlers

Sources: components/src/main/java/org/patternfly/component/menu/MenuToggleMenu.java238-263

Select Components

SingleSelect and SingleSelectMenu

SingleSelect is a specialized component for single-value selection. It extends SingleMenuToggleMenu and uses SingleSelectMenu:

SingleSelect Architecture

The SingleSelectMenu factory creates a pre-configured menu:

When a selection occurs, updateMenuToggle() is called to update the toggle's displayed text with the selected item's text.

Sources: showcase/src/main/java/org/patternfly/showcase/component/SelectComponent.java83-96

MultiSelect and MultiSelectMenu

MultiSelect supports multiple selections, typically with checkboxes. Two factory variants exist:

The checkbox variant uses MenuType.checkbox and SelectionMode.multi, creating checkbox menu items:

MultiSelect with Badge Count

The updateMenuToggle() method in multi-select updates a badge showing the selected count rather than item text.

Sources: showcase/src/main/java/org/patternfly/showcase/component/SelectComponent.java177-193

Typeahead Components

SingleTypeahead Architecture

SingleTypeahead replaces the standard menu toggle button with a search input for filtering:

SingleTypeahead Search Flow

The typeahead is constructed with a SearchInput:

Key initialization in the constructor:

Sets default SearchFilter.contains() filter
Sets default NoResults.noResults() handler
Applies typeahead defaults via TypeaheadSupport.typeaheadDefaults()
Registers keyup handler that expands menu and filters items
Configures stayOpen() predicate to keep menu open when typing

Sources: components/src/main/java/org/patternfly/component/menu/SingleTypeahead.java32-84 components/src/main/java/org/patternfly/component/menu/TypeaheadSupport.java35-59

MultiTypeahead with Label Management

MultiTypeahead uses a FilterInput (which includes a LabelGroup) to display selected items as labels:

MultiTypeahead Label Management

The FilterInput provides textToIdentifier() and textToLabel() functions for converting text to identifiers and creating label components.

The updateMenuToggle() method synchronizes labels with selected items:

Sources: components/src/main/java/org/patternfly/component/menu/MultiTypeahead.java41-156 components/src/main/java/org/patternfly/component/menu/MultiTypeahead.java71-119

Search Filtering

The SearchFilter functional interface defines how items are matched:

Custom filters can be provided via onSearch():

The Menu.search() method applies the filter:

Sources: components/src/main/java/org/patternfly/component/menu/Menu.java368-401 components/src/main/java/org/patternfly/component/menu/NoResults.java22-51

Create New Items Feature

The Typeahead interface provides allowNewItems() to enable dynamic item creation:

This is implemented by TypeaheadSupport.allowNewItems():

The flow:

When no results are found, display a special "create new" menu item
On click, invoke the createItem promise
Add the created item to the menu list
Select it
Update toggle text and collapse menu

Sources: components/src/main/java/org/patternfly/component/menu/TypeaheadSupport.java68-82 showcase/src/main/java/org/patternfly/showcase/component/SelectComponent.java214-233

Advanced Features

Asynchronous Item Loading

MenuItem supports lazy loading of nested items via the async type:

The AsyncItems functional interface returns a promise:

Loading behavior:

Click triggers loadItems() callback
After LOADING_TIMEOUT (1000ms), displays spinner in item text
On promise resolution, removes the async item and adds loaded items to the list
On error, restores original text

The menu tracks async status via hasAsyncItems() and prevents searching during loading:

Sources: components/src/main/java/org/patternfly/component/menu/MenuItem.java136-138 components/src/main/java/org/patternfly/component/menu/MenuItem.java567-602 components/src/main/java/org/patternfly/component/menu/Menu.java268-280

Favorites System

The Menu component supports marking items as favorites when favorites() is enabled. The system maintains two sets of items:

Source items: Original items in regular menu lists
Favorite items: Cloned items in a special favorites group

Favorites System Architecture

The toggleFavorite() method:

The clone constructor creates a favorite item with shared handlers:

Clicking a favorite item triggers the original item's handlers via the sourceItem reference.

Sources: components/src/main/java/org/patternfly/component/menu/Menu.java404-428 components/src/main/java/org/patternfly/component/menu/MenuItem.java244-283

Validation States

Select components can display validation states by integrating with the MenuToggle.validated() method:

The validation status affects the toggle's visual styling and can be paired with HelperText to display messages.

Sources: showcase/src/main/java/org/patternfly/showcase/component/SelectComponent.java147-176

Data Flow Architecture

Selection Data Flow

Sources: components/src/main/java/org/patternfly/component/menu/MenuToggleMenu.java238-263 components/src/main/java/org/patternfly/component/menu/Menu.java310-354 components/src/main/java/org/patternfly/component/menu/MenuItem.java311-338

Component Type Mapping

The following table maps user-facing component names to their Java class implementations:

Component Name	Primary Class	Menu Configuration	Selection Mode
Menu	`Menu`	`menu(menu, click)`	Click (current)
Single Select	`SingleSelect`	`menu(select, single)`	Single (radio)
Multi Select	`MultiSelect`	`menu(select, multi)`	Multi
Multi Select (Checkbox)	`MultiSelect`	`menu(checkbox, multi)`	Multi (checkbox UI)
Single Typeahead	`SingleTypeahead`	`menu(select, single)`	Single + search
Multi Typeahead	`MultiTypeahead`	`menu(select, multi)`	Multi + search + labels

Sources: components/src/main/java/org/patternfly/component/menu/Menu.java95-97 components/src/main/java/org/patternfly/component/menu/SingleTypeahead.java38 components/src/main/java/org/patternfly/component/menu/MultiTypeahead.java41

Menu and Selection Components