vue3-popper

library1.5.0jsnpmunverified

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.

web-framework

npm install vue3-popper

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · VUE3-POPPER

vue3-popper

web-frameworkjavascriptv1.5.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Popper

✓ import Popper from 'vue3-popper';

✗ import { Popper } from 'vue3-popper'; const Popper = require('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)

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

✗ import { defineComponent } from 'vue'; import Popper from 'vue3-popper'; export default defineComponent({ 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.

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>

Debug

Known issues

breakingThe `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.

affects: >=0.6.0

breakingVersion 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.

affects: >=1.4.0

gotchaPrior 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.

affects: <1.4.2

deprecatedOlder 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.

affects: <1.0.0

Errors

Common errors & fixes

ReferenceError: window is not defined

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.

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>`.

Upgrade

Version history

1.5.0latest on npm

Audit

Dependencies

vuerequiredPeer dependency required for Vue 3 application integration.

Agent activity

10 hits · last 30 days

node

Bingbot

OpenAI (training)

Resources

githubhttps://github.com/valgeirb/vue3-popper ↗

packagehttps://www.npmjs.com/package/vue3-popper ↗

homepagehttps://valgeirb.github.io/vue3-popper ↗