# 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="/files/eMajmr8pHRY7fb7QXndv" 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](/ui-building-blocks/widgets/default-properties.md):

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.digia.tech/ui-building-blocks/widgets/layout-structure-widgets/overlay.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.