Dialog Loader for Quasar

🇪🇸 Versión en español | 🇧🇷 Versão em português

Quasar extension for a global loading modal dialog in Vue 3 + Quasar apps, with an imperative composable-based API.

Table of contents

• In 30 seconds
• What it is and what it includes
• Requirements and compatibility
• Install in a Quasar app
• What the extension adds to the host
• Global defaults (boot)
• Language (i18n)
• Quick start
• TypeScript in your IDE
• Public API
• Visual variants
• Loading indicators (spinner)
• Anti-flicker and concurrent operations
• Exported TypeScript types
• Public entrypoints
• Troubleshooting

In 30 seconds

Recommended flow:

1. Install the extension in your Quasar app (quasar ext add).
2. Ensure the host Pinia boot runs before this extension’s boot.
3. Import useDialogLoader() where you run async work.
4. Wrap the task with await loader.run({ task: () => api.save() }) — or { label, task } for a one-off label override.

The extension registers boots and CSS in the host project automatically after quasar ext add.

What it is and what it includes

Global modal dialog controlled by useDialogLoader() — not an embeddable component.

• run({ task }) or run(task) — main case; uses the boot label when you omit label.
• run({ label, task }) — one-off text override without changing boot defaults.
• show() / hide() — manual control with an internal pending-operation counter.
• Three presentation variants: glass, primary, minimal.
• Configurable spinners (curated Quasar subset; default ios).
• Anti-flicker: open/close delays and minimum visible time.
• Global defaults in the host boot (gap, font, variant, spinner…); optional label per call.
• Built-in i18n en, es, pt — follows Quasar $q.lang; boot overrides (locale, messages).
• Controls in task: pause, resume, cancel, and signal (AbortSignal).

Requirements and compatibility

The host Pinia boot must run before this extension’s boot.

Install in a Quasar app

quasar ext add @benjaminor-dev/dialog-loader

Remove:

quasar ext remove @benjaminor-dev/dialog-loader

After quasar ext add, the extension registers boots and CSS automatically. No extra steps for a normal npm install.

What the extension adds to the host

Resources installed or registered by the extension:

Install (quasar ext add / invoke): creates src/boot/bor/bor-dialog-loader-defaults.ts (or .js) and registers it in quasar.config → boot: [] automatically. No manual editing needed in a normal install. Package boot (boot/dialog) and main.css are injected on every dev/build (they do not appear as short entries in quasar.config).

Remove (quasar ext remove): removes the defaults boot and its quasar.config entry.

Minimum boot order:

1. Pinia (host)
2. Dialog Loader — boot/dialog
3. bor/bor-dialog-loader-defaults (host)

In quasar.config you only see bor/bor-dialog-loader-defaults; the package boot/dialog is added by the extension runner at compile time.

The boot mounts the dialog in the document and wires the host Pinia store. You do not import DialogLoader in App.vue.

Global defaults (boot)

Avoid repeating variant, spinner, gap, font, delays, and zIndex on every call. Label priority: run({ label }) / show() → boot label → i18n (locale / $q.lang / en).

After quasar ext add, review src/boot/bor/bor-dialog-loader-defaults.ts — template with all boot options (// recommended: …) and language notes in the file header comment.

// src/boot/bor/bor-dialog-loader-defaults.ts
import { configureDialogLoaderDefaults } from "@benjaminor-dev/quasar-app-extension-dialog-loader";

configureDialogLoaderDefaults({
  // locale: "es", // uncomment to pin a specific language for Dialog Loader
  variant: "glass",
  spinner: "ios",
  openDelayMs: 120,
  hideDelayMs: 450,
  minVisibleMs: 600,
  backdropBlur: "blur(10px)",
  zIndex: 6000,
  gap: "2rem",
  font: {
    family: "Arial, sans-serif",
    size: "1.35rem",
  },
  spinnerColor: {
    light: "primary",
    dark: "white",
  },
  spinnerTrackColor: {
    light: "grey-4",
    dark: "grey-7",
  },
});

Language (i18n)

Built-in en, es, and pt. By default the label follows Quasar language ($q.lang.isoName); if Quasar has no language, fallback is en ("Loading...").

Locale resolution: boot locale → $q.lang.isoName prefix (es* → es, pt* → pt) → en.

Label resolution: run({ label }) / show(label) → boot label → boot messages.loadingLabel → built-in catalog → en.

Built-in message keys: loadingLabel (default loader text), operationCancelled (DialogLoaderRunCancelledError when cancel() aborts the task).

Quasar config example (Spanish for the whole app):

// quasar.config.ts
framework: {
  lang: "es",
},

configureDialogLoader is an alias of configureDialogLoaderDefaults.

If you omit spinnerColor / spinnerTrackColor, fallback depends on variant: on primary the spinner is white; on glass and minimal it uses primary and grey-4. Set { light, dark } in boot to match the host theme ($q.dark).

Quick start

<script setup lang="ts">
import { useDialogLoader } from "@benjaminor-dev/quasar-app-extension-dialog-loader";

const loader = useDialogLoader();

async function onSave() {
  try {
    await loader.run({ task: () => api.save(formData) });
    // notify.success('Saved');
  } catch (error) {
    // notify.error('Save failed');
  }
}
</script>

<template>
  <q-btn label="Save" @click="onSave" />
</template>

No explicit label — uses i18n from $q.lang (e.g. "Cargando..." with lang: 'es'):

await loader.run(() => fetchUsers());
// equivalent:
await loader.run({ task: () => fetchUsers() });

One-off label override:

await loader.run({ label: "Saving...", task: () => api.save(formData) });

Optional controls inside task:

await loader.run({
  task: async ({ pause, resume, cancel, signal }) => {
    await api.prepare();
    pause(); // hide overlay; task keeps running
    await api.finishInBackground();
    resume(); // show loader again
    await fetch("/api/finalize", { signal }); // cancel() aborts this fetch
  },
});

pause(), resume(), and cancel() are idempotent and only affect that run() call.

import { DialogLoaderRunCancelledError } from "@benjaminor-dev/quasar-app-extension-dialog-loader";

try {
  await loader.run({ task: ({ signal }) => fetch(url, { signal }) });
} catch (error) {
  if (error instanceof DialogLoaderRunCancelledError) return;
  throw error;
}

Manual control (less common):

loader.show("Processing...");
try {
  await longTask();
} finally {
  loader.hide();
}

TypeScript in your IDE

Do not memorize the API — let autocomplete guide you.

• useDialogLoader() returns DialogLoaderApi — methods and refs appear when you type loader..
• In configureDialogLoaderDefaults({ ... }), Ctrl+Space (Windows/Linux) or Cmd+Space (macOS) lists variant, spinner, spinnerColor, spinnerTrackColor, gap, font, openDelayMs, etc.
• variant accepts "glass" \| "primary" \| "minimal"; spinner accepts DIALOG_LOADER_SPINNER_TYPES values (e.g. "ios", "dots", "circular").
• run() — overloads: run(task) or run({ task, label? }); in task, destructure { pause, resume, cancel, signal } with inferred types.
• In boot, locale accepts "en" \| "es" \| "pt"; messages accepts partial DialogLoaderMessages (loadingLabel, operationCancelled).
• Hover a method: the tooltip shows parameters and JSDoc.

If something does not autocomplete, it is usually a nonexistent prop or wrong import — check the main entrypoint before searching this README.

Public API

Entry point: useDialogLoader().

import { useDialogLoader } from "@benjaminor-dev/quasar-app-extension-dialog-loader";

const loader = useDialogLoader();

Methods

Reactive state (read-only)

When to use run vs show / hide

Visual variants

Set variant in the host boot (or built-in).

Loading indicators (spinner)

Set spinner in boot. Curated subset of Quasar spinners:

Exported constant: DIALOG_LOADER_SPINNER_TYPES — useful to validate values at runtime.

Anti-flicker and concurrent operations

The store keeps a pendingCount: each show() / run() start increments it; each hide() / run() end decrements it. UI closes only when the counter reaches zero.

Configurable delays in boot:

• openDelayMs — do not show if all operations finish before this (very fast requests).
• minVisibleMs — avoid an immediate close flash after open.
• hideDelayMs — align close with overlay fade animation.

Concurrent run() or show() calls share the same dialog until all finish.

Exported TypeScript types

From the main entrypoint:

import {
  useDialogLoader,
  DialogLoaderRunCancelledError,
  resolveDialogLoaderMessages,
  resolveExtensionLocale,
  type DialogLoaderApi,
  type DialogLoaderRunControls,
  type DialogLoaderRunOptions,
  type DialogLoaderRunTask,
  type DialogLoaderDefaults,
  type DialogLoaderFontDefaults,
  type DialogLoaderMessages,
  type DialogLoaderThemeColor,
  type DialogLoaderThemeColorValue,
  type DialogLoaderThemeMode,
  type DialogLoaderVariant,
  type DialogLoaderSpinnerType,
  type ExtensionLocale,
  type ResolvedDialogLoaderDefaults,
} from "@benjaminor-dev/quasar-app-extension-dialog-loader";

Also exported: BUILTIN_DIALOG_LOADER_DEFAULTS, DIALOG_LOADER_SPINNER_TYPES, resolveDialogLoaderMessages, resolveExtensionLocale, configureDialogLoader (alias), and DIALOG_LOADER_API_KEY (boot provide key for advanced integrations).

Public entrypoints

What you import in your code:

Boot (boot/dialog) and styles (main.css) are registered by the extension in quasar.config on install — no manual import in a normal setup.

Troubleshooting

I see "Loading..." and want Spanish (or Portuguese)

Without Quasar language config, the default is English. Pick one line:

// quasar.config.ts — recommended (whole Quasar app)
framework: {
  lang: "es", // or "pt-BR" via Quasar lang pack in boot
},

// src/boot/bor/bor-dialog-loader-defaults.ts — pin Dialog Loader locale only
configureDialogLoaderDefaults({ locale: "es" });

Override a single string:

configureDialogLoaderDefaults({ messages: { loadingLabel: "Cargando..." } });

Label does not update when switching language during run()

If the user changes app language while the loader is visible, the on-screen label keeps the text from when run() / show() started. After the loader closes, the idle label follows the new locale. To pin a language for the whole extension, use locale in boot.

Boots or styles missing from quasar.config

Under normal conditions, install registers the defaults boot in boot: [] and the runner injects boot/dialog + CSS at compile time. If the defaults boot is missing:

npx quasar ext invoke @benjaminor-dev/dialog-loader

Error: Pinia not initialized

• Verify a Pinia boot in the host (app.use(pinia) or equivalent).
• In quasar.config, Pinia boot must run before this extension’s dialog boot.

useDialogLoader() outside setup

Call it inside setup, another composable, or <script setup>. The boot must have run (app mounted).

Loader flickers on fast requests

Adjust boot: increase openDelayMs, minVisibleMs, or both.

Loader does not close after show()

Each show() needs a matching hide() (or use run(), which balances automatically).

Dialog stays behind another overlay

Check zIndex in boot (default 6000).

Changed spinner in boot and nothing updates

Restart the dev server. Confirm you edit the host’s src/boot/bor/bor-dialog-loader-defaults.ts, not only the extension template.

MIT © Benjamín Olvera R.