# Overlay Components

Overlay components float above the page: confirmation dialogs, side drawers, popovers, tooltips, toasts, and loading-state placeholders. Floating components (popover, tooltip, hover-card) share `floatingSide`/`floatingAlign` positioning, and dialog-family components open from a `trigger` and trap focus while open. All accept the shared `props` bag plus `visibility` and `responsive` modules.

```yaml
components:
  - type: dialog
    title: Confirm
    trigger: { type: button, content: 'Open' }
    children:
      - { type: text, content: 'Are you sure?' }
```

## `dialog`

A modal dialog opened from a trigger. Clicking the backdrop or pressing Escape closes it; focus is trapped within the dialog while open.

| Property      | Description                                          |
| ------------- | ---------------------------------------------------- |
| `title`       | Dialog heading.                                      |
| `description` | Supporting text below the title.                     |
| `trigger`     | The element that opens the dialog when clicked.      |
| `children`    | Components rendered inside the dialog panel.         |
| `props`       | HTML attributes (e.g. `className` for panel sizing). |

## `alert-dialog`

A confirmation dialog for destructive actions, with explicit confirm/cancel buttons.

| Property       | Description                                           |
| -------------- | ----------------------------------------------------- |
| `content`      | The confirmation message.                             |
| `confirmLabel` | Label for the confirm button.                         |
| `cancelLabel`  | Label for the cancel button.                          |
| `trigger`      | The element that opens the alert dialog.              |
| `action`       | The action invoked on confirm (e.g. a `crud` delete). |

## `drawer`

A panel that slides in from a screen edge.

| Property     | Description                                                       |
| ------------ | ----------------------------------------------------------------- |
| `drawerSide` | Edge the drawer slides in from: `left`, `right`, `top`, `bottom`. |
| `drawerSize` | Size preset: `sm`, `md`, `lg`, `full`.                            |
| `trigger`    | The element that opens the drawer.                                |
| `children`   | Components rendered inside the drawer panel.                      |

## `popover`

A floating panel anchored to a trigger, opened on click.

| Property        | Description                                                                |
| --------------- | -------------------------------------------------------------------------- |
| `trigger`       | The element that opens the popover.                                        |
| `floatingSide`  | Preferred side relative to the trigger (`top`, `right`, `bottom`, `left`). |
| `floatingAlign` | Alignment along that side (`start`, `center`, `end`).                      |
| `children`      | Components rendered inside the popover.                                    |

## `tooltip`

A small hover hint anchored to a trigger.

| Property         | Description                             |
| ---------------- | --------------------------------------- |
| `tooltipContent` | The hint text.                          |
| `tooltipDelay`   | Delay before the tooltip appears (ms).  |
| `floatingSide`   | Preferred side relative to the trigger. |
| `floatingAlign`  | Alignment along that side.              |

## `hover-card`

A richer popover that opens on hover (e.g. a profile preview).

| Property        | Description                                         |
| --------------- | --------------------------------------------------- |
| `trigger`       | The element that reveals the card on hover.         |
| `floatingSide`  | Preferred side relative to the trigger.             |
| `floatingAlign` | Alignment along that side.                          |
| `openDelay`     | Delay before opening on hover (ms).                 |
| `closeDelay`    | Delay before closing after the pointer leaves (ms). |
| `children`      | Components rendered inside the card.                |

## `toast`

A transient notification. Toasts are usually emitted from an action's `onSuccess`/`onError` handler rather than placed in the tree directly; page-level placement is configured via [`page.toasts`](/en/docs/pages-overview#page-properties).

| Property      | Description                                                                  |
| ------------- | ---------------------------------------------------------------------------- |
| `variant`     | Style: `success`, `error`, `warning`, `info` (also `default`/`destructive`). |
| `message`     | Toast text (supports `$variable` references).                                |
| `duration`    | Auto-dismiss duration in milliseconds (default: 5000).                       |
| `actionLabel` | Optional action-button label.                                                |
| `actionUrl`   | Optional URL the action button navigates to.                                 |

Multiple toasts stack without overlapping; position is configured per page (e.g. `top-right`, `bottom-center`).

## `progress`

A progress bar or circular indicator showing completion.

| Property                | Description                                                                                |
| ----------------------- | ------------------------------------------------------------------------------------------ |
| `progressValue`         | Current value.                                                                             |
| `progressMax`           | Maximum value.                                                                             |
| `props.showLabel`       | Display the percentage text alongside the bar.                                             |
| `props.size`            | Size preset (e.g. `sm` for a thinner bar).                                                 |
| `props.progressVariant` | Set to `circle` for a circular progress indicator with the percentage shown in the center. |

## `skeleton`

A loading placeholder shown while content is fetching.

| Property          | Description                                  |
| ----------------- | -------------------------------------------- |
| `skeletonVariant` | Shape: `text`, `circular`, or `rectangular`. |
| `skeletonWidth`   | Placeholder width.                           |
| `skeletonHeight`  | Placeholder height.                          |
| `props.animate`   | Set `true` for a pulsing animation.          |

## Related Pages

- [Pages Overview](/en/docs/pages-overview) — actions, `onSuccess`/`onError` handlers, page toasts.
- [Layout Components](/en/docs/layout-components) — the `modal` layout component.
- [Form Controls](/en/docs/form-controls) — inputs commonly hosted in dialogs and drawers.
- [Feedback Components](/en/docs/feedback-components) — progress, spinner, skeleton.
- [Data Components](/en/docs/data-components) — record-detail drawers triggered from a data-table.