Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time



npm version npm downloads license build coverage size

Popper for Svelte with actions, no wrapper components or component bindings required!

Other Popper libraries for Svelte (including the official @popperjs/svelte library) use a wrapper component that takes the required DOM elements as props. Not only does this require multiple bind:this, you also have to pollute your script tag with multiple DOM references.

We can do better with Svelte actions!


$ npm i -D svelte-popperjs

Since Svelte automatically bundles all required dependencies, you only need to install this package as a dev dependency with the -D flag.

Due to a configuration issue with PopperJS, this will not work in the Svelte REPL. However, svelte-popperjs works with Rollup, Vite, and SvelteKit!


createPopperActions takes an optional options object for configuring the popper instance, and returns a pair of actions to be used on the reference and popper elements.

The content action also takes an options object for updating the options of the popper instance.


A Svelte version of the standard tutorial.

  import { createPopperActions } from 'svelte-popperjs';
  const [popperRef, popperContent] = createPopperActions({
    placement: 'right',
    strategy: 'fixed',
  const extraOpts = {
    modifiers: [
      { name: 'offset', options: { offset: [0, 8] } }

  let showTooltip = false;

  on:mouseenter={() => showTooltip = true}
  on:mouseleave={() => showTooltip = false}
  My button
{#if showTooltip}
  <div id="tooltip" use:popperContent={extraOpts}>
    My tooltip
    <div id="arrow" data-popper-arrow />


Setting popper options

Popper options can be set statically when creating the popper actions, or dynamically on the content action.

If both are set, then the dynamic options will be merged with the initial options.

  // set once and no longer updated
  const [popperRef, popperContent] = createPopperActions(initOptions);

<!-- will be merged with initOptions -->
<div use:popperContent={dynamicOptions}/>

Virtual elements

PopperJS allows the reference node to be a virtual element which is not mounted on the DOM and cannot be used with Svelte actions.

Despite this, svelte-popperjs provides first-class support for virtual elements, and even supports reactive updates to the virtual element with Svelte stores.

Here's an example creating a tooltip that follows the mouse cursor.

  import { writable } from 'svelte/store';
  import { createPopperActions } from 'svelte-popperjs';
  const [popperRef, popperContent] = createPopperActions({
    strategy: 'fixed',
  let x = 0;
  let y = 0;
  const mousemove = (ev: MouseEvent) => {
    x = ev.clientX;
    y = ev.clientY;
  $: getBoundingClientRect = () => ({
    width: 0, height: 0,
    top: y, bottom: y,
    left: x, right: x,
  const virtualElement = writable({ getBoundingClientRect });
  $: $virtualElement = { getBoundingClientRect };
<svelte:window on:mousemove={mousemove} />

  <div use:popperContent>Tooltip</div>

Accessing the Popper instance

If access is needed to the raw Popper instance created by the actions, you can reference the third element returned by createPopperActions. The third element is a function that will return the current Popper instance used by the actions.

Using the raw Popper instance to manually recompute the popper's position.

  import { createPopperActions } from 'svelte-popperjs';
  const [popperRef, popperContent, getInstance] = createPopperActions();

  async function refreshTooltip() {
    const newState = await getInstance().update();