Positioning

usePosition answers one question: where should the floating element sit relative to the anchor?

It only runs when node.open.value is true. When the surface is closed, it cleans up all scroll listeners, resize observers, and animation frames.

Placement

A placement tells usePosition which side of the anchor to use and how to align along that side:

• Sides: top, bottom, left, right
• Alignments: -start, -end, or centered by default

For example, bottom-start places the surface below the anchor, aligned to its starting edge.

usePosition(node, {
  placement: "bottom-start",
});

Middlewares refine coordinates

Raw coordinates are rarely enough. Elements hit screen boundaries, overlap their triggers, or need spacing.

Middlewares run sequentially to adjust the computed position:

• offset: Adds spacing between the anchor and the floating element.
• flip: Flips the element to the opposite side if it overflows the viewport.
• shift: Shifts the element along its axis to stay in view.
• size: Constrains the element width or height to available space.

usePosition(node, {
  placement: "top",
  middlewares: {
    offset: 8,
    flip: true,
    shift: { padding: 8 },
  },
});

Automatic style application

By default, usePosition synchronizes position, top, left, and transform directly onto node.refs.floatingEl.

You do not need to bind :style in your template:

<template>
  <button ref="anchorEl">Trigger</button>
  <!-- Styles are applied directly to floatingEl -->
  <div v-if="node.open.value" ref="floatingEl">Floating content</div>
</template>

If you need manual control, pass { applyStyles: false }. usePosition returns reactive styles you can bind yourself:

const { styles } = usePosition(node, { applyStyles: false });

Real and virtual anchors

The anchor does not have to be a real DOM element. It can be a virtual element that provides a getBoundingClientRect() method.

For cursor tracking and context menus, useClientPoint handles this automatically by creating a virtual anchor from pointer coordinates.

Where to go next

• Middlewares: How middlewares refine coordinates, resolve collisions, and execute in sequence.
• Virtual anchors: How to position against pointer events, context menus, and text selections.
• Animations and transitions: How to animate floating surfaces without layout jumps.
• usePosition API: Full options and return values.
• useClientPoint API: Virtual anchor helper for cursor positioning.