# Overlays and mount targets

AsukaDesigner standardizes overlay mounting without forcing every overlay into the same container.

The key rule is: **defaults depend on the overlay type**.

## Default behavior

- Drawers open inside the central designer content by default.
- Modals open at viewport/body level by default.
- Tooltips open at viewport/body level by default.
- Floating overlays, popovers, and panels keep their module/host behavior unless a target is provided.

This makes drawers feel embedded in the product designer while keeping modal dialogs suitable for focused fullscreen tasks.

## Configure a mount target on one item

```ts
const designer = createAsukaDesigner('#app', {
  layout: {
    left: {
      items: [
        {
          kind: 'download',
          label: 'Download',
          icon: 'download',
          type: 'drawer',
          mountTarget: '#download-drawer-host',
        },
      ],
    },
  },
});
```

`mountTarget` accepts a CSS selector or an `HTMLElement`.

## Change a target at runtime

```ts
designer.util.modules.setMountTarget('download', '#download-drawer-host');
designer.util.modules.clearMountTarget('download');
```

## Recommended containers

Use stable IDs for custom hosts:

```html
<div id="product-designer">
  <main id="designer-main-content"></main>
  <div id="download-drawer-host"></div>
</div>
```

Then reference them from configuration:

```ts
mountTarget: '#download-drawer-host'
```

Avoid generic selectors such as `main` when multiple designers can exist on the same page.

## Stateful overlays

Some overlays are stateful and should only open when their payload exists. Examples include:

- `element-editor`
- `element-variation-picker`

The host guards those overlays so a stale async module load cannot reopen an empty overlay after it was cancelled.

## `keepMounted` and click blocking

Hidden overlays that are kept mounted must also become inert. OverlayHost applies hidden/inert behavior so a visually closed overlay cannot leave a backdrop that blocks clicks.

## Related guides

- [Layout](./layout.md)
- [Built-in modules](./modules-built-in.md)
- [State and persistence](./state-and-persistence.md)