{"id":15924,"library":"vue3-popper","title":"Vue 3 Popper Component","description":"vue3-popper is a lightweight and flexible popover component for Vue 3 applications, leveraging PopperJS v2 for accurate positioning. Currently at version 1.5.0, it follows semantic versioning strictly since its 1.0.0 release. The library offers features like configurable placement, offsets, hover triggers, arrows, and manual control of visibility. It is designed to be highly customizable, supporting both simple string content via props and complex HTML structures through slots. Recent updates have focused on improving SSR compatibility (especially with Nuxt 3), refactoring to modern Vue 3 `script setup` syntax, and enhancing type definitions. Its key differentiators include its tight integration with Vue 3's reactive system and its commitment to providing a robust wrapper around the proven PopperJS library, making it a reliable choice for tooltips and popovers in the Vue ecosystem.","status":"active","version":"1.5.0","language":"javascript","source_language":"en","source_url":"https://github.com/valgeirb/vue3-popper","tags":["javascript","vue-popper-component","vue-3-popper","vue-3-popover","vue-3-popper-SFC","popper-2","vue-3-popper-2"],"install":[{"cmd":"npm install vue3-popper","lang":"bash","label":"npm"},{"cmd":"yarn add vue3-popper","lang":"bash","label":"yarn"},{"cmd":"pnpm add vue3-popper","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency required for Vue 3 application integration.","package":"vue","optional":false}],"imports":[{"note":"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.","wrong":"import { Popper } from 'vue3-popper';\nconst Popper = require('vue3-popper');","symbol":"Popper","correct":"import Popper from 'vue3-popper';"},{"note":"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`.","wrong":"import { defineComponent } from 'vue';\nimport Popper from 'vue3-popper';\nexport default defineComponent({\n  components: { Popper },\n  // ...\n});","symbol":"Popper (in Options API)","correct":"import Popper from 'vue3-popper';\nexport default {\n  components: { Popper },\n  // ...\n}"},{"note":"With Vue 3's `<script setup>` syntax, components imported directly into the script block are automatically made available in the template without explicit registration.","symbol":"Popper (in Script Setup)","correct":"<script setup>\nimport Popper from 'vue3-popper';\n</script>"}],"quickstart":{"code":"<template>\n  <section style=\"display: flex; gap: 20px; justify-content: center; padding: 50px;\">\n    <Popper content=\"Hello, I am a simple string Popper!\">\n      <button>Click for simple content</button>\n    </Popper>\n\n    <Popper placement=\"right\" hover arrow :offset-distance=\"15\">\n      <button>Hover for complex content</button>\n      <template #content>\n        <div style=\"padding: 10px; background-color: #333; color: white; border-radius: 5px;\">\n          <h4>Interactive Popover</h4>\n          <p>This popover supports <b>HTML content</b> and is triggered on hover.</p>\n          <button style=\"background-color: lightblue; border: none; padding: 5px 10px; margin-top: 10px; cursor: pointer;\">Action</button>\n        </div>\n      </template>\n    </Popper>\n\n    <Popper :show=\"showManualPopper\" :offset-skid=\"10\">\n      <button @click=\"showManualPopper = !showManualPopper\">Toggle Manual Popper</button>\n      <template #content>\n        <div>Manually controlled popover!</div>\n      </template>\n    </Popper>\n  </section>\n</template>\n\n<script setup lang=\"ts\">\nimport Popper from 'vue3-popper';\nimport { ref } from 'vue';\n\nconst showManualPopper = ref(false);\n</script>\n\n<style>\nbody { font-family: sans-serif; margin: 0; }\nbutton { padding: 10px 15px; border: 1px solid #ccc; background-color: #f0f0f0; cursor: pointer; border-radius: 4px; }\n</style>","lang":"typescript","description":"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."},"warnings":[{"fix":"Replace `offsetX` with `offsetSkid` and `offsetY` with `offsetDistance` in your component usage.","message":"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.","severity":"breaking","affected_versions":">=0.6.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=1.4.0"},{"fix":"Upgrade to `vue3-popper@1.4.2` or higher to resolve the SSR `window` undefined error in Nuxt 3.","message":"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.","severity":"gotcha","affected_versions":"<1.4.2"},{"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.","message":"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.","severity":"deprecated","affected_versions":"<1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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.","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.","error":"ReferenceError: window is not defined"},{"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>`.","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.","error":"[Vue warn]: Component is missing template or render function."}],"ecosystem":"npm"}