Vue 3 Draggable Popover

A small Vue 3 component that renders a draggable popover card using Teleport.

Install

npm install vue3-draggable-popover

Usage

<script setup lang="ts">
import { DraggablePopover } from "vue3-draggable-popover";
import "vue3-draggable-popover/style.css";
import { ref } from "vue";
import type { Component } from "vue";

const PopoverBody: Component = {
  props: {
    customEmitter: Function
  },
  template: `<div>
    <div>Content goes here</div>
    <button type="button" @click="customEmitter?.('cta-clicked', { source: 'body' })">
      Notify parent
    </button>
  </div>`,
};

const popoverRef = ref<InstanceType<typeof DraggablePopover> | null>(null);

function showPopover() {
  popoverRef.value?.show();
}

function hidePopover() {
  popoverRef.value?.hide();
}
</script>

<template>
  <DraggablePopover
    ref="popoverRef"
    :start-x="120"
    :start-y="80"
    :body="PopoverBody"
    title="Details"
    subtitle="Drag me"
    :rounded="true"
    :draggable="true"
    :show="true"
    :persist-position="true"
    persist-id="kickoff-tips"
    :show-close="true"
    :z-index="1056"
    @dragging="({ x, y }) => console.log('dragging', x, y)"
    @dragged="({ x, y }) => console.log('dragged', x, y)"
    @close="hidePopover"
    @custom="({ name, payload }) => console.log('custom', name, payload)"
  />

  <button type="button" @click="showPopover">Show</button>
  <button type="button" @click="hidePopover">Hide</button>
</template>

Props

• startX (number, default 0): Initial X position in pixels.
• startY (number, default 0): Initial Y position in pixels.
• body (Component, optional): Body component to render.
• title (string, optional): Title text shown in the header.
• subtitle (string, optional): Subtitle text shown under the title.
• rounded (boolean, default true): Rounded corners when true.
• draggable (boolean, default true): Enables dragging when true.
• show (boolean, default true): Controls visibility when using the prop.
• persistPosition (boolean, default false): Save/restore position to localStorage.
• persistId (string, optional): Identifier used for localStorage key when persistPosition is true.
• showClose (boolean, default false): Shows a close button in the header.
• zIndex (number, default 1056): Z-index for the popover.

Events

• dragging: Emits { x, y } while dragging.
• dragged: Emits { x, y } after dragging ends.
• close: Emits when the close button is clicked.
• custom: Emits { name, payload } from the body via customEmitter.

Methods

Use a template ref to call:

• show(): Shows the popover (internal state).
• hide(): Hides the popover (internal state).

Body emitter

The body component can accept a customEmitter prop and call it to bubble events up:

customEmitter?.("event-name", { any: "payload" });

Persistence

When persistPosition is enabled and persistId is provided, the position is stored in localStorage under a key like _id:your-id and restored on mount.