Vue 3 Popper Component

Common errors

• ReferenceError: window is not defined

  cause This error typically occurs in a Server-Side Rendering (SSR) environment (like Nuxt 3) when `vue3-popper` attempts to access the `window` object during server compilation, before it's available in the browser.
  fix Upgrade `vue3-popper` to version 1.4.2 or higher, which includes a fix for this specific SSR issue. If using an older version is unavoidable, consider dynamically importing the component or rendering it only on the client-side.

• [Vue warn]: Component is missing template or render function.

  cause This warning usually means the `Popper` component was imported or registered incorrectly, or Vue couldn't find its template. This can happen with incorrect default/named imports or CJS `require` in an ESM context.
  fix Ensure you are using `import Popper from 'vue3-popper';` (default import) and registering it correctly in your Vue component's `components` option or directly in `<script setup>`.

Warnings

• breaking The `offsetX` and `offsetY` props were renamed to `offsetSkid` and `offsetDistance` respectively. This change affects how positioning offsets are configured and was introduced in v0.6.0, becoming official in v1.0.0.
  Fix: Replace `offsetX` with `offsetSkid` and `offsetY` with `offsetDistance` in your component usage.
• breaking Version 1.4.0 introduced significant internal refactors, moving to Vue 3's `script setup` syntax and replacing the click-away directive with composables. While not strictly API-breaking for typical usage, custom implementations or reliance on the old directive might require adjustments.
  Fix: Review custom click-away logic or direct manipulation of internal directive behavior. Ensure your Vue 3 project is up-to-date and using modern composition API practices.
• gotcha Prior to version 1.4.2, `vue3-popper` could encounter issues with `window` being undefined when rendering in a Nuxt 3 SSR (Server-Side Rendering) context, leading to hydration mismatches or server errors.
  Fix: Upgrade to `vue3-popper@1.4.2` or higher to resolve the SSR `window` undefined error in Nuxt 3.
• deprecated Older versions (prior to v1.0.0) had less strict semantic versioning. From v1.0.0 onwards, the package strictly adheres to semantic versioning, meaning major versions will introduce breaking changes.
  Fix: Always check release notes for breaking changes when upgrading major versions (e.g., v1.x.x to v2.x.x) or when upgrading from pre-1.0.0 versions.

Install

• npm install vue3-popper npm
• yarn add vue3-popper yarn
• pnpm add vue3-popper pnpm

Imports

• Popper
  wrong:

  import { Popper } from 'vue3-popper';
  const Popper = require('vue3-popper');

  correct:

  import Popper from 'vue3-popper';

  Popper is a default export. The component is intended for use in Vue 3 applications, which typically use ESM. While the library itself ships types, the main export is a default one.
• Popper (in Options API)
  wrong:

  import { defineComponent } from 'vue';
  import Popper from 'vue3-popper';
  export default defineComponent({
    components: { Popper },
    // ...
  });

  correct:

  import Popper from 'vue3-popper';
  export default {
    components: { Popper },
    // ...
  }

  When using the Options API, `Popper` must be explicitly registered in the `components` option. The `defineComponent` helper from Vue is often used but not strictly required for component registration itself, nor is it imported from `vue3-popper`.
• Popper (in Script Setup)

  <script setup>
  import Popper from 'vue3-popper';
  </script>

  With Vue 3's `<script setup>` syntax, components imported directly into the script block are automatically made available in the template without explicit registration.

Quickstart

This quickstart demonstrates `vue3-popper` with simple string content, complex slot content with hover trigger and arrow, and a manually controlled popover, all within a Vue 3 `<script setup>` context.

<template>
  <section style="display: flex; gap: 20px; justify-content: center; padding: 50px;">
    <Popper content="Hello, I am a simple string Popper!">
      <button>Click for simple content</button>
    </Popper>

    <Popper placement="right" hover arrow :offset-distance="15">
      <button>Hover for complex content</button>
      <template #content>
        <div style="padding: 10px; background-color: #333; color: white; border-radius: 5px;">
          <h4>Interactive Popover</h4>
          <p>This popover supports <b>HTML content</b> and is triggered on hover.</p>
          <button style="background-color: lightblue; border: none; padding: 5px 10px; margin-top: 10px; cursor: pointer;">Action</button>
        </div>
      </template>
    </Popper>

    <Popper :show="showManualPopper" :offset-skid="10">
      <button @click="showManualPopper = !showManualPopper">Toggle Manual Popper</button>
      <template #content>
        <div>Manually controlled popover!</div>
      </template>
    </Popper>
  </section>
</template>

<script setup lang="ts">
import Popper from 'vue3-popper';
import { ref } from 'vue';

const showManualPopper = ref(false);
</script>

<style>
body { font-family: sans-serif; margin: 0; }
button { padding: 10px 15px; border: 1px solid #ccc; background-color: #f0f0f0; cursor: pointer; border-radius: 4px; }
</style>