Dialog Message for Quasar

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

Quasar extension for modal message dialogs (alerts and confirmation) 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 presets
• Icon and buttons by theme
• Alerts vs confirmation
• 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 useDialogMessage() where you show feedback to the user.
4. Call await message.success() (i18n preset) or await message.success({ text: '...' }); for confirm: const ok = await message.confirm({ text: '...' }).

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 useDialogMessage() — not an embeddable component.

• Alert presets — success, info, warn, error (single Accept button).
• Confirmation — confirm() with two buttons (Cancel / Confirm) and Promise<boolean>.
• Defaults per preset in the host boot (title, icon, iconColor, labels).
• Built-in i18n en, es, pt — presets and buttons follow $q.lang; boot overrides (locale, messages, presets).
• Light / dark theme — iconColor: { light, dark } and global or per-preset buttonStyle.
• Per-call override — title, text, icon, colors, button variants, and labels.
• onAccept / onCancel — optional side-effects when buttons are pressed.
• hide() — imperative close without running callbacks.
• persistent — prevents closing via backdrop or Esc (configurable in boot).

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-message

Remove:

quasar ext remove @benjaminor-dev/dialog-message

After quasar ext add, the extension registers boots and CSS in your app automatically. No extra steps are needed 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-message-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 Message — boot/dialog
3. bor/bor-dialog-message-defaults (host)

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

The boot mounts the dialog in the document and connects the host Pinia store. You do not need to import DialogMessage in App.vue.

Global defaults (boot)

Avoid repeating titles, icons, labels, and measurements on every call. Priority: per-call options → host boot → i18n (locale / $q.lang / en).

After quasar ext add, review src/boot/bor/bor-dialog-message-defaults.ts — template with language instructions in the file comment.

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

configureDialogMessageDefaults({
  // locale: "es", // uncomment to pin a specific language for Dialog Message
  width: "420px",
  persistent: true,
  zIndex: 7000,
  gap: "1rem",
  actionsGap: "2rem",
  font: {
    family: "Arial, sans-serif",
    sizeTitle: "1.4rem",
    sizeText: "1.2rem",
  },
  buttonStyle: {
    light: {
      acceptColor: "primary",
      acceptVariant: "unelevated",
      cancelColor: "primary",
      cancelVariant: "outline",
    },
    dark: {
      acceptColor: "primary",
      acceptVariant: "unelevated",
      cancelColor: "white",
      cancelVariant: "outline",
    },
  },
});

Language (i18n)

Built-in en, es, and pt for preset titles, texts, and labels (success, info, warn, error, confirm). By default follows $q.lang; without a Quasar language, falls back to en.

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

Text resolution: per-call options → boot presets.<variant> → boot messages → built-in catalog → en. Icons and default colors come from built-in visuals; override visuals in boot presets.

Spanish across the whole app:

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

Override a single preset (visual + text):

configureDialogMessageDefaults({
  presets: {
    confirm: { title: "Delete record?", acceptLabel: "Delete" },
  },
});

Override i18n strings without changing icons:

configureDialogMessageDefaults({
  messages: {
    acceptLabel: "Got it",
    presets: { warn: { title: "Heads up", text: "Check your input" } },
  },
});

configureDialogMessage is an alias of configureDialogMessageDefaults.

Each preset includes title, text, and labels per language. Boot presets can override both text and visuals (icon, iconColor, button styles); boot messages overrides text only.

Preset variants: success, info, warn, error, confirm.

Per-field priority: call → preset (boot) → i18n → global (boot). Within buttons, buttonStyle.<theme> wins over flat acceptColor / cancelColor at the same level.

Quick start

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

const message = useDialogMessage();

async function onSave() {
  try {
    await api.save(formData);
    await message.success(); // i18n preset (title + text)
    // await message.success({ text: "Record saved" });
  } catch (error) {
    await message.error({ text: "Could not save" });
  }
}

async function onDelete(item: { id: string }) {
  const confirmed = await message.confirm({
    title: "Delete record",
    text: "The selected record will be deleted. Do you want to continue?",
  });
  if (!confirmed) return;

  await api.delete(item.id);
  await message.success({ text: "Record deleted" });
}
</script>

<template>
  <q-btn label="Save" @click="onSave" />
  <q-btn label="Delete" color="negative" @click="onDelete({ id: '1' })" />
</template>

Alert with a one-off title and icon override:

await message.info({
  title: "Important notice",
  text: "Review the data before continuing",
  icon: "campaign",
  iconColor: "warning",
});

Confirm with button override only in dark mode:

const ok = await message.confirm({
  text: "Do you want to continue?",
  buttonStyle: {
    dark: { cancelColor: "grey-4" },
  },
});
if (!ok) return;

Side-effect on accept (e.g. logout):

await message.warn({
  text: "Your session will expire in 5 minutes",
  onAccept: async () => {
    await auth.refreshSession();
  },
});

TypeScript in your IDE

Do not memorize the API — let autocomplete guide you.

• useDialogMessage() returns DialogMessageApi — methods and refs appear when you type message..
• In configureDialogMessageDefaults({ ... }), Ctrl+Space / Cmd+Space lists presets, buttonStyle, gap, font, zIndex, etc.
• Inside presets.success, presets.confirm, etc., the IDE suggests title, text, icon, iconColor, acceptLabel, cancelLabel, buttonStyle.
• In font, the IDE suggests family, sizeTitle, sizeText.
• iconColor accepts a plain string or { light, dark }; buttonStyle groups button colors and variants per theme.
• success / info / warn / error accept optional DialogMessageOptions; confirm accepts optional DialogMessageConfirmOptions (adds cancelLabel, cancelColor, cancelVariant, onCancel).
• In boot, locale accepts "en" \| "es" \| "pt"; messages accepts partial DialogMessageI18nMessages (global labels and nested presets.<variant>).
• confirm() resolves Promise<boolean>; alert presets resolve Promise<void> when Accept is pressed.
• Hover over a method: the tooltip shows parameters and JSDoc.

If something does not appear in autocomplete, it is usually a non-existent prop or a wrong import — check the main entrypoint before searching the README.

Public API

Entry point: useDialogMessage().

import { useDialogMessage } from "@benjaminor-dev/quasar-app-extension-dialog-message";

const message = useDialogMessage();

Methods

Reactive state (read-only)

Per-call options (DialogMessageOptions)

DialogMessageConfirmOptions extends the above with:

Visual presets

Configure each preset in boot presets (or use the built-ins). Texts follow i18n; icons and default colors are locale-independent unless you override them in boot.

Exported constant: DIALOG_MESSAGE_VARIANTS — list of valid variants.

Icon and buttons by theme

The dialog resolves colors based on $q.dark.isActive (light / dark).

Icon — iconColor

In boot (per preset) or per call:

iconColor: { light: "negative", dark: "red-4" }
// or flat (same color in both themes):
iconColor: "positive"

Buttons — buttonStyle

Global in boot (applies to all presets) or partial per preset / call:

buttonStyle: {
  light: {
    acceptColor: "primary",
    acceptVariant: "unelevated",
    cancelColor: "primary",
    cancelVariant: "outline",
  },
  dark: {
    acceptColor: "primary",
    acceptVariant: "unelevated",
    cancelColor: "white",
    cancelVariant: "outline",
  },
}

Per-theme fields in buttonStyle: acceptColor, acceptVariant, cancelColor, cancelVariant.

Built-in variants: Accept → unelevated, Cancel → outline.

Alerts vs confirmation

Only one dialog can be visible at a time. A new call closes the previous session (pending confirm resolves false).

Exported TypeScript types

From the main entrypoint:

import {
  useDialogMessage,
  resolveDialogMessageMessages,
  resolveExtensionLocale,
  type DialogMessageApi,
  type DialogMessageOptions,
  type DialogMessageConfirmOptions,
  type DialogMessageDefaults,
  type DialogMessagePresetConfig,
  type DialogMessagePresetsDefaults,
  type DialogMessageFontDefaults,
  type DialogMessageI18nMessages,
  type PartialDialogMessageI18nMessages,
  type DialogMessageButtonStyleConfig,
  type DialogMessageButtonThemeStyle,
  type DialogMessageButtonVariant,
  type DialogMessageThemeColor,
  type DialogMessageThemeColorValue,
  type DialogMessageThemeMode,
  type DialogMessageVariant,
  type ExtensionLocale,
  type ResolvedDialogMessageDefaults,
  configureDialogMessageDefaults,
  BUILTIN_DIALOG_MESSAGE_DEFAULTS,
  DIALOG_MESSAGE_VARIANTS,
} from "@benjaminor-dev/quasar-app-extension-dialog-message";

Also exported: configureDialogMessage (alias), resolveDialogMessageMessages, resolveExtensionLocale, BUILTIN_DIALOG_MESSAGE_DEFAULTS, and DIALOG_MESSAGE_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 needed for a normal install.

Troubleshooting

I see titles or buttons in English and want Spanish (or Portuguese)

Without configuring Quasar, built-in presets are in English. Pick one option:

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

// src/boot/bor/bor-dialog-message-defaults.ts — pin Dialog Message locale only
configureDialogMessageDefaults({ locale: "es" });

Boots or styles do not appear in 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-message

Error: Pinia not initialized

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

useDialogMessage() outside setup

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

The dialog does not show a title

• Check if you passed title: "" (hides the title on purpose).
• If you omit title, presets.<variant>.title from boot is used.

confirm() always resolves false

• Check that you are not calling hide() or opening another dialog before pressing a button.
• A second call while the first is open closes the previous one with false.

The dialog stays behind another overlay

Adjust zIndex in boot (default 7000) according to your app’s layer hierarchy.

I changed presets in boot and nothing updates

Restart the dev server. Confirm you are editing src/boot/bor/bor-dialog-message-defaults.ts in the host, not only the extension template.

MIT © Benjamín Olvera R.