Vue SweetAlert2 Wrapper

Common errors

• Property '$swal' does not exist on type 'ComponentPublicInstance'.

  cause The `vue-sweetalert2` plugin was not correctly installed using `app.use()` in your Vue application's entry point.
  fix Ensure `app.use(VueSweetalert2);` is called before `app.mount('#app');` in your main application file (e.g., `main.ts` or `main.js`).

• SweetAlert2: The parameter is expected to be of type Object, but got type String.

  cause Passing a string directly to `this.$swal()` or `this.$swal.fire()` without wrapping it in an object. SweetAlert2's modern API expects a configuration object as its primary parameter.
  fix Always pass a configuration object to SweetAlert2 methods, even for simple alerts. For example, use `this.$swal({ title: 'Hello', text: 'World!' });` instead of `this.$swal('Hello world!');`.

• SweetAlert2 modal appears without any styling or looks broken.

  cause The core SweetAlert2 CSS file (`sweetalert2/dist/sweetalert2.min.css`) is not being loaded or is being overridden by conflicting styles. This can happen due to the `Prevent auto import of sweetalert style` feature in `v4.2.0+` or incorrect Nuxt.js configuration.
  fix Verify that `import 'sweetalert2/dist/sweetalert2.min.css';` is present in your application's entry file. If using Nuxt.js, check your `nuxt.config.js` for proper module configuration (e.g., `sweetalert` options or `no-css` module combined with manual CSS import).

Warnings

• gotcha The package maintainer explicitly recommends against using `vue-sweetalert2` with Vue 3 Composition API. It is advised to import and use `sweetalert2` directly for better integration feedback and alignment with its native documentation when using Composition API.
  Fix: For Composition API, `import Swal from 'sweetalert2';` and use `Swal.fire(...)` directly. For Options API, continue using `this.$swal`.
• breaking Version `3.0.5` introduced a 'Disable force css including' feature, which was subsequently reverted in `3.0.6`. This could lead to inconsistent CSS loading behavior if not explicitly handled, potentially causing SweetAlert2 modals to render without styling in specific build setups.
  Fix: Always ensure manual import of `sweetalert2/dist/sweetalert2.min.css` in your main entry file, especially if upgrading or downgrading around these versions, to guarantee styles are loaded.
• gotcha Starting from `v4.2.0`, a feature to 'Prevent auto import of sweetalert style' was added. This means the `sweetalert2.min.css` might no longer be automatically included by the plugin, which can result in unstyled modals.
  Fix: Explicitly add `import 'sweetalert2/dist/sweetalert2.min.css';` to your main JavaScript/TypeScript entry file (e.g., `main.ts` or `main.js`) to ensure styles are applied.
• gotcha When integrating `vue-sweetalert2` with Nuxt.js, specific module paths must be used, such as `vue-sweetalert2/nuxt` or `vue-sweetalert2/nuxt/no-css`. Using the incorrect or generic package path can lead to improper injection of `$swal` or missing styles.
  Fix: Follow the Nuxt.js specific integration guide in the README, configuring your `nuxt.config.js` to use `modules: ['vue-sweetalert2/nuxt']` or `modules: ['vue-sweetalert2/nuxt/no-css']` as needed.

Install

• npm install vue-sweetalert2 npm
• yarn add vue-sweetalert2 yarn
• pnpm add vue-sweetalert2 pnpm

Imports

• VueSweetalert2
  wrong:

  const VueSweetalert2 = require('vue-sweetalert2');

  correct:

  import VueSweetalert2 from 'vue-sweetalert2';

  This is the primary plugin export used with `app.use()` for global installation. While `require()` might work in some CJS contexts, ESM import is standard for modern Vue projects.
• sweetalert2/dist/sweetalert2.min.css

  import 'sweetalert2/dist/sweetalert2.min.css';

  This stylesheet is crucial for the default SweetAlert2 styling. As of v4.2.0, auto-import of styles can be prevented, requiring explicit manual import for proper rendering.
• $swal
  wrong:

  import { $swal } from 'vue-sweetalert2';

  correct:

  this.$swal('Hello Vue world!!!');

  The `$swal` method is injected globally onto the Vue instance and component context (e.g., `app.config.globalProperties.$swal` for Vue 3, or `this.$swal` in Options API components). It is not a direct named export from the package.

Quickstart

This quickstart demonstrates how to install and configure `vue-sweetalert2` in a Vue 3 application, including setting global SweetAlert2 options and examples of triggering different types of alerts from a component using the injected `this.$swal` method.

import { createApp } from 'vue';
import App from './App.vue';
import VueSweetalert2 from 'vue-sweetalert2';
import 'sweetalert2/dist/sweetalert2.min.css'; // Essential for default styling

const app = createApp(App);

// Optional: Configure global SweetAlert2 options
const options = {
  confirmButtonColor: '#41b882',
  cancelButtonColor: '#ff7674',
};

app.use(VueSweetalert2, options);
app.mount('#app');

// App.vue (example component)
<template>
  <div>
    <h1>Vue SweetAlert2 Demo</h1>
    <button @click="showSuccessAlert">Show Success Alert</button>
    <button @click="showErrorPrompt">Show Error Prompt</button>
  </div>
</template>

<script lang="ts">
import { defineComponent } from 'vue';

export default defineComponent({
  name: 'App',
  methods: {
    async showSuccessAlert() {
      await this.$swal({
        title: 'Operation Successful!',
        text: 'Your action was completed successfully.',
        icon: 'success',
        confirmButtonText: 'OK',
      });
    },
    async showErrorPrompt() {
      const { value: text } = await this.$swal.fire({
        title: 'Why did the error occur?',
        input: 'textarea',
        inputPlaceholder: 'Type your reason here...',
        inputAttributes: {
          'aria-label': 'Type your reason here'
        },
        showCancelButton: true,
      });

      if (text) {
        this.$swal.fire('Reason provided:', text);
      }
    },
  },
});
</script>