vue-use-popperjs

2.3.8 verified Fri May 01 auth: no javascript

Vue 3 composable and directive for integrating Popper.js v2.x positioning engine. Current stable version 2.3.8, actively maintained. Provides both a usePopper composable and a v-popper directive for tooltips, popovers, and dropdowns. Ships TypeScript definitions. Peer dependency on Vue 3.2.37+. Key differentiator: lightweight, composable-first approach vs heavier alternatives like Vuetify tooltips.

Common errors

error Cannot find module 'vue-use-popperjs' or its corresponding type declarations. ↓

cause Missing TypeScript types or incorrect import path.

fix

Ensure package is installed: npm install vue-use-popperjs. If using TS, check tsconfig includes node_modules types.

error Uncaught (in promise) TypeError: Cannot read properties of null (reading 'usePopper') ↓

cause VueUsePopperjs not installed as plugin; usePopper not globally available.

fix

Import { usePopper } from 'vue-use-popperjs' directly in component instead of relying on global.

Warnings

breaking vue-use-popperjs v2 requires Vue 3 and is not compatible with Vue 2. ↓

fix Use vue-use-popperjs v1.x for Vue 2 projects.

breaking In v2, the plugin no longer auto-registers the v-popper directive. Must call app.use(VueUsePopperjs) explicitly. ↓

fix Install plugin: app.use(VueUsePopperjs) or import and use VPopper directly.

deprecated The v-popper directive is deprecated in v2.4+; use the usePopper composable instead. ↓

fix Migrate from v-popper to usePopper composable.

gotcha TypeScript types for attributes.popper are loose; may require manual type assertion for full Popper options. ↓

fix Cast attributes.value.popper as PopperAttributes if strict types needed.

gotcha The library requires @popperjs/core v2.x; using v1.x will break. ↓

fix Install @popperjs/core@^2.0.0.

Install

npm install vue-use-popperjs

yarn add vue-use-popperjs

pnpm add vue-use-popperjs

Imports

usePopper

wrong

import usePopper from 'vue-use-popperjs'

correct

import { usePopper } from 'vue-use-popperjs'

Named export, not default.

VPopper

wrong

import { vPopper } from 'vue-use-popperjs'

correct

import { VPopper } from 'vue-use-popperjs'

Directive export is PascalCase; use as 'v-popper' in templates.

default

wrong

import { VueUsePopperjs } from 'vue-use-popperjs'

correct

import VueUsePopperjs from 'vue-use-popperjs'

Only useful for Vue plugin registration; otherwise use named exports.

Quickstart

Shows plugin registration, usePopper composable with TypeScript, and Vue 3 template usage.

import { createApp } from 'vue';
import App from './App.vue';
import VueUsePopperjs from 'vue-use-popperjs';

const app = createApp(App);
app.use(VueUsePopperjs);

// In a component:
<script setup lang="ts">
import { ref } from 'vue';
import { usePopper } from 'vue-use-popperjs';

const reference = ref<HTMLElement | null>(null);
const popper = ref<HTMLElement | null>(null);
const { styles, attributes } = usePopper(reference, popper, {
  placement: 'bottom',
  modifiers: [{ name: 'offset', options: { offset: [0, 8] } }]
});
</script>

<template>
  <button ref="reference">Hover me</button>
  <div ref="popper" :style="styles.popper" v-bind="attributes.popper">
    Tooltip content
  </div>
</template>