README.md

svelte-popperjs

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!

Installation

$ 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!

Usage

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.

Example

A Svelte version of the standard tutorial.

<script>
  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;
</script>

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

API

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.

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

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

<script>
  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 };
  popperRef(virtualElement);
</script>
<svelte:window on:mousemove={mousemove} />

<main>
  <div use:popperContent>Tooltip</div>
</main>

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.

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

  async function refreshTooltip() {
    const newState = await getInstance().update();
  }
</script>