The App Extension adds the stylesheet for you.

If you install the UI package directly, import the stylesheet in your boot file or app entry:

import '@quasar/quasar-ui-qoverlay/dist/index.css'

Quasar CLI projects can also centralize the stylesheet in quasar.config.ts:

// Note: using ~ tells Quasar the file resides in node_modules
css: [
  "app.scss",
  "~@quasar/quasar-ui-qoverlay/dist/index.css",
],

Keep runtime component registration in the App Extension and import only the component instance type in <script setup>:

import { useTemplateRef } from 'vue'
import type { QOverlay } from '@quasar/quasar-ui-qoverlay'

const overlayRef = useTemplateRef<QOverlay>('overlay')

A normal value import of QOverlay creates a local component binding in <script setup> and takes precedence over the globally registered component. Use a normal import only when you intend to use the UI component directly, and follow the manual boot file installation path instead of registering it through both paths.

Because application source imports the type, add the UI package as a direct application dependency:

pnpm add @quasar/quasar-ui-qoverlay

Applications that only use the globally registered component in templates do not need this extra direct dependency.

Yes. After the App Extension is installed, run:

quasar describe QOverlay

The same generated API is shown on the Using QOverlay page.

Use QOverlay when part of the UI must be temporarily blocked while an operation completes. It is especially useful for background saves, refresh actions, permission checks, and short transitions before opening another piece of UI.

Yes. Put the component in QOverlay’s default slot. QOverlay will wrap it and place the overlay over that component only.

Yes. The overlay background uses CSS colors, so you can tune the color and opacity for light or dark layouts.

Use the body slot for content such as a spinner, progress message, or close button.