| [ Web Proxy ] |
| Viewing: https://deepwiki.com/patternfly-java/patternfly-java/5.4-overlay-components | [Back] [Original] |
This page documents the overlay components in PatternFly Java: Modal, Popover, and Tooltip. These components display content that appears above the main page content, either blocking interaction (Modal) or providing contextual information without blocking (Popover, Tooltip).
All three components share common patterns:
For wizard workflows that can be displayed in modals, see page 5.7. For additional positioning concepts, see page 4.6. </old_str> <new_str>
This document describes overlay and feedback components in PatternFly Java. The primary overlay components are Modal, Popover, and Tooltip, which share common positioning infrastructure via Popper.js and follow consistent patterns for triggering, lifecycle management, and event handling. This page also covers Alert and AlertGroup for inline user feedback, and EmptyState for placeholder content when no data exists.
For wizard workflows that can be displayed in modals, see page 5.7. For drawer components that slide in from the side, refer to the drawer implementation in layout components (page 5.8).
Modal, Popover, and Tooltip share a common architectural foundation built on Popper.js for positioning and the Attachable pattern for lifecycle management. They implement the Closeable interface for consistent close behavior. Alert, AlertGroup, and EmptyState are feedback components that do not use Popper.js positioning.
Overlay Component Class Hierarchy
Component Comparison
| Component | Base Class | Key Interfaces | Positioning | Primary Use Case |
|---|---|---|---|---|
Modal | ComponentDelegate | Attachable, Closeable | Full-page overlay (Backdrop) | Focused tasks requiring user attention |
Popover | BaseComponent | Attachable, Closeable, ComponentIcon, NoPadding | Popper.js | Rich contextual content with headers/footers |
Tooltip | BaseComponent | Attachable, Closeable | Popper.js | Brief text-based hints on hover/focus |
Sources: components/src/main/java/org/patternfly/component/popover/Popover.java86-90 components/src/main/java/org/patternfly/component/tooltip/Tooltip.java72-75
Popover and Tooltip components use Popper.js for dynamic positioning relative to trigger elements. The integration is managed through PopperBuilder, which configures positioning modifiers, trigger actions, and animation behavior.
Sources: components/src/main/java/org/patternfly/component/popover/Popover.java162-196 components/src/main/java/org/patternfly/component/tooltip/Tooltip.java166-196
Both Popover and Tooltip use PopperBuilder in their attach() method to create Popper instances:
Configuration Options:
| Option | Default (Popover) | Default (Tooltip) | Description |
|---|---|---|---|
animationDuration | 300ms | 300ms | Fade in/out animation duration |
distance | 25px | 15px | Distance from trigger element |
zIndex | 9999 | 9999 | CSS z-index for stacking |
entryDelay | N/A | 300ms | Delay before showing (Tooltip only) |
exitDelay | N/A | 300ms | Delay before hiding (Tooltip only) |
placement | top | top | Initial placement preference |
flip | true | true | Auto-flip if no space |
Sources: components/src/main/java/org/patternfly/component/popover/Popover.java114-150 components/src/main/java/org/patternfly/component/tooltip/Tooltip.java114-154
The Modal component creates full-page overlays that block interaction with the underlying page. Unlike Popover and Tooltip, Modal does not use Popper.js positioning and instead centers content using a Backdrop component that covers the entire viewport.
Modal Element Hierarchy
Modal Factory Methods and Builder Pattern
When using addWizard(), Modal automatically manages the wizard lifecycle by registering cancel and finish handlers to close the modal.
Sources: showcase/src/main/java/org/patternfly/showcase/component/WizardComponent.java305-323
Modal State Transitions
Key Lifecycle Methods
| Method | Description |
|---|---|
appendToBody() | Appends modal to document.body |
appendTo(Node) | Appends modal to specified parent node |
open() | Shows backdrop, adds visibility CSS, registers ESC key handler |
close(Event, boolean) | Hides backdrop, removes ESC handler, fires CloseHandler events |
closeOnEsc(boolean) | Controls whether pressing ESC closes the modal (default: true) |
autoClose(boolean) | Controls whether clicking backdrop closes the modal |
Size Variants
Close Behavior
Sources: showcase/src/main/java/org/patternfly/showcase/component/WizardComponent.java305-323
The Popover component displays rich contextual content in an overlay positioned relative to a trigger element. It supports headers, bodies, footers, icons, and status indicators.
Sources: components/src/main/java/org/patternfly/component/popover/Popover.java135-158
Popover uses the TriggerAction enum to define when it should appear:
Available TriggerAction values: click, mouseenter, mouseleave, focus, blur
Sources: components/src/main/java/org/patternfly/component/popover/Popover.java119-144 components/src/main/java/org/patternfly/component/popover/Popover.java357-363
Popover content is organized using three sub-components:
Sub-component Structure
| Class | Factory Method | Element | Purpose |
|---|---|---|---|
PopoverHeader | popoverHeader() | <header> | Title and optional icon |
PopoverBody | popoverBody() | <div> | Main content area |
PopoverFooter | popoverFooter() | <footer> | Action buttons or links |
PopoverHeader Icon Management
PopoverHeader includes an internal icon container that can be populated via Popover.icon():
The icon is inserted before the header text element using insertBefore() in PopoverHeader.failSafeIconContainer().
Sources: components/src/main/java/org/patternfly/component/popover/PopoverHeader.java87-100 components/src/main/java/org/patternfly/component/popover/Popover.java299-311
Popover supports severity status with automatic icon and styling:
When status() is called:
Available Severity Values:
Severity.default_ - Neutral informationalSeverity.info - Informational (blue)Severity.success - Success (green)Severity.warning - Warning (orange)Severity.danger - Error or critical (red)Sources: components/src/main/java/org/patternfly/component/popover/Popover.java326-338
Sources: components/src/main/java/org/patternfly/component/popover/Popover.java92-429
The Tooltip component provides simple text-based hints that appear on hover or focus. It is lighter-weight than Popover and optimized for brief explanatory text.
| Feature | Tooltip | Popover |
|---|---|---|
| Content | Text only | Rich HTML with header/body/footer |
| Trigger | mouseenter, focus (default) | click (default) |
| Close Button | No | Optional via closable() |
| Entry/Exit Delays | Yes (300ms default) | No |
| Use Case | Brief hints, labels | Complex contextual information |
Sources: components/src/main/java/org/patternfly/component/tooltip/Tooltip.java69-341
Sources: components/src/main/java/org/patternfly/component/tooltip/Tooltip.java136-163
Tooltip manages ARIA attributes on the trigger element through the TriggerAria enum:
When the tooltip shows, it adds the appropriate ARIA attribute to the trigger element:
Sources: components/src/main/java/org/patternfly/component/tooltip/Tooltip.java148-149 components/src/main/java/org/patternfly/component/tooltip/Tooltip.java317-323
Sources: components/src/main/java/org/patternfly/component/tooltip/Tooltip.java78-341
Popover implements the NoPadding interface to allow removal of default padding:
This is useful when embedding components that have their own padding (e.g., lists, tables).
Sources: components/src/main/java/org/patternfly/component/popover/Popover.java88
All three overlay components implement the Closeable interface, which provides a consistent event handling pattern for close operations.
Sources: components/src/main/java/org/patternfly/component/modal/Modal.java286-291 components/src/main/java/org/patternfly/component/modal/Modal.java315-325
Registration:
Sources: components/src/main/java/org/patternfly/component/modal/Modal.java286-291 components/src/main/java/org/patternfly/component/popover/Popover.java272-286
Overlay components integrate with other PatternFly components to create rich user experiences.
Sources: components/src/main/java/org/patternfly/component/tabs/Tab.java265-297
The Tab component supports both help() and tooltip() methods to attach overlays:
Tab with Popover Help and Tooltip
Implementation Detail: Both the help popover and tooltip are stored on the Tab instance but are actually added to the parent Tabs element during Tabs.attach(). This is necessary because Tab elements are inside a scrolling container (<ul>) that would clip the overlay if it were attached directly to the tab.
The Tab class includes:
Popover help field components/src/main/java/org/patternfly/component/tabs/Tab.java117Tooltip tooltip field components/src/main/java/org/patternfly/component/tabs/Tab.java118Button helpButton for triggering popover components/src/main/java/org/patternfly/component/tabs/Tab.java119When help() is called, it creates a help button with the PatternFly help icon and stores the popover for later attachment.
Sources: components/src/main/java/org/patternfly/component/tabs/Tab.java117-285 components/src/main/java/org/patternfly/component/tabs/Tab.java291-297
Modals commonly host wizard components for multi-step workflows. See the Wizard in Modal example:
For complete details on wizard workflows, see page 5.7.
Sources: showcase/src/main/java/org/patternfly/showcase/component/WizardComponent.java305-323
Overlay components provide consistent patterns for displaying content over the main page:
| Component | Positioning | Trigger | Content Complexity | Primary Use Case |
|---|---|---|---|---|
Modal | Full page (Backdrop) | Programmatic | High (headers, bodies, wizards) | Focused tasks requiring user attention |
Popover | Popper.js | Event-based | Medium (headers, bodies, footers) | Contextual help and information |
Tooltip | Popper.js | Event-based | Low (text only) | Brief hints and labels |
Common Patterns:
Attachable for lifecycle managementCloseable for consistent close behaviorPopperBuilder for positioningBackdrop for full-page overlaysKey Design Decisions:
Sources: components/src/main/java/org/patternfly/component/modal/Modal.java1-336 components/src/main/java/org/patternfly/component/popover/Popover.java1-429 components/src/main/java/org/patternfly/component/tooltip/Tooltip.java1-341
Refresh this wiki
Enter email to refresh| Web Proxy Viewer | New URL | Original Page |