Svelte attachment for floating-ui. Position floating elements like tooltips, popovers, and dropdowns with automatic reactivity - most modern floating-ui wrapper for svelte.

Installation and requirement

npm install svelte-floating-attach @floating-ui/dom

@floating-ui/dom is a peer dependency, not bundled into this package. You need to install it alongside to prevent version conflicts.

• Svelte >=5.29.0 (attachment support)
• @floating-ui/dom >=1.6.0

Why this library?

This library is heavily inspired by svelte-floating-ui. If you're on ≤ Svelte 5.29 you should use that library instead.

svelte-floating-attach requires ≥ Svelte 5.29. It uses attachments ({@attach}) API. Attachments work better than actions.

What's different from svelte-floating-ui?

| | svelte-floating-attach | svelte-floating-ui | | --------------------------- | ----------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | | Reactivity | Automatic — attachment re-runs when any $state in its arguments changes | Manual (if using runes) — requires $effect + update() to sync prop changes | | Arrow/caret positioning | Automatic — left/top styles applied to the arrow element after each computation | Manual — you read middlewareData.arrow in onComputed and apply styles yourself | | @floating-ui/dom | Peer dependency — installed separately, no duplicates | Direct dependency — bundled in, may duplicate if you also depend on it directly | | Svelte stores | None — plain closures | Uses writable stores for arrow refs and virtual elements | | Bundle footprint | ~5 KB compiled (re-exports from your existing @floating-ui/dom) | Bundles its own copy of @floating-ui/dom into the package |

Automatic reactivity

Actions (use:) don't re-run when their arguments change. With svelte-floating-ui, you need a manual $effect to push updated options:

<script>
  import { createFloatingActions } from 'svelte-floating-ui'
  import { flip, offset, shift } from 'svelte-floating-ui/dom'

  let { placement = $bindable('bottom') } = $props()

  const [floatingRef, floatingContent, updatePosition] = createFloatingActions({
    placement,
    middleware: [offset(8), shift(), flip()],
  })

  // Required: manually sync reactive props to the action
  $effect(() => {
    updatePosition({ placement })
  })
</script>

<button use:floatingRef>Trigger</button>
<div use:floatingContent>Content</div>

Attachments run in the template's reactive tracking context — when placement changes, the attachment tears down and re-runs with the new value. No $effect, no update():

<script>
  import { createFloating, flip, offset, shift } from 'svelte-floating-attach'

  let { placement = $bindable('bottom') } = $props()

  const { ref, content } = createFloating()
</script>

<button {@attach ref}>Trigger</button>
<div {@attach content({
  placement,
  middleware: [offset(8), shift(), flip()],
})}>
  Content
</div>

Automatic arrow/caret positioning

In svelte-floating-ui, you create a writable store for the arrow element and manually apply its computed position inside onComputed:

<script>
  import { createFloatingActions, arrow } from 'svelte-floating-ui'
  import { createArrowRef } from 'svelte-floating-ui'

  const arrowRef = createArrowRef()

  const [floatingRef, floatingContent] = createFloatingActions({
    middleware: [arrow({ element: arrowRef })],
    onComputed({ placement, middlewareData }) {
      // You must manually read and apply arrow styles
      const { x, y } = middlewareData.arrow
      const staticSide = { top: 'bottom', right: 'left', bottom: 'top', left: 'right' }[
        placement.split('-')[0]
      ]
      Object.assign($arrowRef.style, {
        left: x != null ? `${x}px` : '',
        top: y != null ? `${y}px` : '',
        [staticSide]: '-4px',
      })
    },
  })
</script>

<div use:floatingContent>
  Content
  <div bind:this={$arrowRef} class="arrow"></div>
</div>

In svelte-floating-attach, this is built in. The library automatically applies left/top from middlewareData.arrow to the arrow element after every computation, and resets stale right/bottom when placement changes:

<script>
  import { createFloating, offset, flip, shift } from 'svelte-floating-attach'

  const { ref, content, arrow, arrowMiddleware } = createFloating()
</script>

<div {@attach content({
  placement: 'top',
  middleware: [offset(8), flip(), shift(), arrowMiddleware({ padding: 4 })],
})}>
  Content
  <div {@attach arrow} class="arrow"></div>
</div>

Usage

Basic Popover

<script>
  import { createFloating, offset, flip, shift } from 'svelte-floating-attach'

  let show = $state(false)
  const { ref, content } = createFloating()
</script>

<button {@attach ref} onclick={() => show = !show}>
  Toggle
</button>

{#if show}
  <div {@attach content({
    placement: 'bottom',
    middleware: [offset(8), flip(), shift()],
  })}>
    Popover content
  </div>
{/if}

Reactive Placement (Component Props)

A complete example showing how placement reacts to prop changes and how onComputed keeps the actual placement in sync when Floating UI flips it due to lack of space.

<!-- Popover.svelte -->
<script lang="ts">
  import type { Snippet } from 'svelte'
  import type { Placement } from 'svelte-floating-attach'
  import { createFloating, offset, flip, shift, hide } from 'svelte-floating-attach'

  interface Props {
    /** Preferred placement — may be overridden by flip() */
    placement?: Placement
    show?: boolean
    children?: Snippet
    content?: Snippet
  }

  let {
    placement = $bindable('bottom'),
    show = $bindable(false),
    children,
    content: contentSnippet,
  }: Props = $props()

  const { ref, content: floatingContent } = createFloating()
</script>

<button {@attach ref} onclick={() => show = !show}>
  {@render children?.()}
</button>

{#if show}
  <div {@attach floatingContent({
    placement,
    middleware: [offset(8), shift(), flip(), hide()],
    onComputed: (data) => (placement = data.placement),
  })}>
    {@render contentSnippet?.()}
  </div>
{/if}

When the consumer passes a different placement prop, the attachment re-runs automatically — no $effect needed. The onComputed callback writes back the actual placement so the consumer always knows where the popover ended up (e.g., 'top' instead of 'bottom' after a flip).

<!-- Consumer.svelte -->
<script>
  import Popover from './Popover.svelte'

  let placement = $state('bottom')
</script>

<select bind:value={placement}>
  <option value="top">Top</option>
  <option value="bottom">Bottom</option>
  <option value="left">Left</option>
  <option value="right">Right</option>
</select>

<Popover bind:placement>
  {#snippet content()}
    Placed at: {placement}
  {/snippet}
  Click me
</Popover>

Tooltip with Arrow

The library automatically applies left/top from middlewareData.arrow to the arrow element, positioning it along the edge to stay centered on the reference. It also resets stale right/bottom values when placement changes.

<script>
  import { createFloating, offset, flip, shift } from 'svelte-floating-attach'

  let show = $state(false)
  const { ref, content, arrow, arrowMiddleware } = createFloating()
</script>

<button
  {@attach ref}
  onmouseenter={() => show = true}
  onmouseleave={() => show = false}
>
  Hover me
</button>

{#if show}
  <div {@attach content({
    placement: 'top',
    middleware: [offset(8), flip(), shift(), arrowMiddleware({ padding: 4 })],
  })}>
    Tooltip text
    <div {@attach arrow} class="arrow"></div>
  </div>
{/if}

Pushing the arrow onto the edge

The library positions the arrow along the correct edge (centering it on the reference) but does not push it onto the edge itself — that depends on your arrow's size and visual design. Use onComputed to offset the arrow so it pokes out of the floating element:

<script>
  import { createFloating, offset, flip, shift } from 'svelte-floating-attach'

  let show = $state(false)
  let arrowEl = $state()
  const { ref, content, arrow, arrowMiddleware } = createFloating()

  function onComputed(data) {
    if (!arrowEl) return

    // The side of the floating element that faces the reference:
    //   placement "top"    → arrow sits on "bottom" edge
    //   placement "bottom" → arrow sits on "top" edge
    //   placement "left"   → arrow sits on "right" edge
    //   placement "right"  → arrow sits on "left" edge
    const side = data.placement.split('-')[0]
    const oppositeSide = { top: 'bottom', right: 'left', bottom: 'top', left: 'right' }[side]

    // Nudge the arrow outward so it straddles the edge (half in, half out)
    arrowEl.style[oppositeSide] = `${-arrowEl.offsetWidth / 2}px`
  }
</script>

<button
  {@attach ref}
  onmouseenter={() => show = true}
  onmouseleave={() => show = false}
>
  Hover me
</button>

{#if show}
  <div {@attach content({
    placement: 'top',
    middleware: [offset(8), flip(), shift(), arrowMiddleware({ padding: 4 })],
    onComputed,
  })}>
    Tooltip text
    <div bind:this={arrowEl} {@attach arrow} class="arrow"></div>
  </div>
{/if}

<style>
  .arrow {
    position: absolute;
    width: 10px;
    height: 10px;
    background: inherit;
    transform: rotate(45deg);
  }
</style>

Without this offset the arrow stays fully inside the floating element. The offset value controls how much it pokes out — use -offsetWidth / 2 to center it on the edge, or any other value that fits your design.

Virtual Element

<script>
  import { createFloating, createVirtualElement, offset } from 'svelte-floating-attach'

  const virtual = createVirtualElement({
    getBoundingClientRect: { x: 0, y: 0, top: 0, left: 0, bottom: 0, right: 0, width: 0, height: 0 }
  })

  const { setVirtualReference, content } = createFloating()
  setVirtualReference(virtual)

  let show = $state(false)
</script>

<div
  onmouseenter={() => show = true}
  onmouseleave={() => show = false}
  onmousemove={(e) => {
    virtual.update({
      getBoundingClientRect: {
        x: e.clientX, y: e.clientY,
        top: e.clientY, left: e.clientX,
        bottom: e.clientY, right: e.clientX,
        width: 0, height: 0,
      }
    })
  }}
>
  Hover area
</div>

{#if show}
  <div {@attach content({ strategy: 'fixed', placement: 'right-start', middleware: [offset(16)] })}>
    Following cursor
  </div>
{/if}

API

createFloating()

Creates a floating instance. Returns:

| Property | Type | Description | | --------------------- | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- | | ref | Attachment | Attach to the reference/trigger element | | content | (options?) => Attachment | Returns an attachment for the floating element | | arrow | Attachment | Attach to the arrow/caret element. left/top styles are applied automatically from middlewareData.arrow after each position computation. | | arrowMiddleware | (options?) => Middleware | Creates arrow middleware using the captured arrow element. Use in the middleware array passed to content(). | | setVirtualReference | (el: VirtualElement) => void | Set a virtual element as the reference |

FloatingContentOptions

Options passed to content(). See Floating UI docs for details on placement, strategy, and middleware.

| Option | Type | Default | Description | | ------------ | --------------------------------------------------------------------- | ------------ | ----------------------------------------------------------------------- | | placement | Placement | 'bottom' | Where to place the floating element | | strategy | Strategy | 'absolute' | CSS positioning strategy | | middleware | Middleware[] | undefined | Floating UI middleware array | | autoUpdate | boolean \| AutoUpdateOptions | true | Auto-update on scroll/resize | | onComputed | (data: ComputePositionReturn) => void | undefined | Callback after position computation |

createVirtualElement(config)

Creates a mutable virtual element for non-DOM references (e.g., cursor position). Call .update(config) to change the position.

Re-exports

All middleware and types from @floating-ui/dom are re-exported for convenience, so you only need one import source.

License

MIT