# Overlay

{% embed url="<https://youtu.be/H9tM7qjowIE?si=MlWvrFj-swXBJufG>" %}

Watch this on Youtube: <https://www.youtube.com/watch?v=H9tM7qjowIE>

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.

<figure><img src="https://3626461507-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FbhApDTL7kHrXte2TTtjs%2Fuploads%2Fgit-blob-2555199d67762cf6618363dd6f0f4361413a8f19%2Foverlay.gif?alt=media" alt="A demonstration of the Overlay widget showing popup content appearing above the main widget."><figcaption><p>The Overlay widget displays floating UI elements like menus, tooltips, and dropdowns on top of main content.</p></figcaption></figure>

### 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](https://docs.digia.tech/ui-building-blocks/widgets/default-properties "mention"):

**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.