Overlay

The Overlay widget is used to display a widget on top of another widget. It’s ideal for floating UI elements like pop-up menus, tooltips, dropdowns, and custom dialogs that appear above the main content.

The Overlay widget displays floating UI elements like menus, tooltips, and dropdowns on top of main content.

Core Concepts

1. Base vs Popup Content

   • childWidget is the main widget that always stays visible (e.g., button, icon, text).

   • popupWidget is the floating content that appears on top (e.g., menu, tooltip, card).

2. Positioning & Alignment

   • childAlignment controls how the main child is aligned inside the Overlay.

   • popupAlignment defines where the popup appears relative to the child (top, bottom, left, right, center, etc.).

   • offset.xAxis / offset.yAxis fine-tune the position to nudge the popup slightly up/down/left/right.

3. Dismiss Behavior

   • dismissOnTapOutside → Close the popup when the user taps anywhere outside it.

   • dismissOnTapInside → Close the popup when the user taps inside the popup itself (good for simple info views or one-tap dismiss).

These controls make the Overlay feel natural and predictable for users.

Properties

Property	Description
childAlignment	Alignment of the main childWidget inside the Overlay.
popupAlignment	Alignment of the popupWidget relative to the main child (e.g., above, below, centered).
offset.xAxis / offset.yAxis	Horizontal and vertical offset applied to the popup’s position to adjust its exact placement.
dismissOnTapOutside	If true, tapping outside the popup hides it.
dismissOnTapInside	If true, tapping inside the popup hides it.

Children of Overlay

Slot	Description
childWidget	The single main child widget that is always visible (e.g., button, icon, text).
popupWidget	The single child widget displayed as the popup on top of the main content (e.g., tooltip, menu, card).

Default Properties

The Overlay widget supports the following section of Default Properties:

Layout

• width

• height

• padding

• margin

• align

Use Cases

Use the Overlay widget when you want to:

• Show a popup menu when a button is tapped (e.g., more options, actions menu).

• Display a tooltip near an icon or label to give extra information.

• Create dropdowns for filters, selectors, or input fields.

• Show floating panels like small info cards, quick actions, or contextual menus.

• Build lightweight custom popups that don’t require full-screen dialogs or navigation.

Anywhere you need a temporary, floating UI attached to a trigger widget, Overlay fits perfectly.