For the complete documentation index, see llms.txt. This page is also available as Markdown.

x-float

The directive and magic for floating one element next to another with Floating UI: placement, collision handling, sizing, and update strategies.

The directive and magic for floating one element next to another with Floating UI: placement, collision handling, sizing, and update strategies.

Directive / magic
What it does

x-float="reference"

Floats the element next to the reference element. A falsey expression disables floating

x-float="{ … }"

Options object instead of a bare reference (see Options)

.top / .bottom-start / .left-end / …

Preferred placement, any Floating UI placement string. With no placement modifier, auto placement picks the side with the most space

.offset / .offset.10px

Distance from the reference (bare .offset is 20px)

.flip

Flips to the opposite side when out of space. Throws when combined with .auto

.auto / .auto-x / .auto-y

Picks the side with the most space: any side, left/right only, or top/bottom only

.shift / .shift-cross / .shift-both

Slides along the reference to stay in view: main axis, cross axis, or both

.cover

Positions over the reference instead of beside it

.fit-x / .fit-y

Caps max-width / max-height to the available space

.match

Matches the reference's width (its height for left/right placements)

.pad / .pad.10px

Boundary padding used by flip, shift, and fit (bare .pad is 5px)

.update

Repositions on scroll and resize

.absolute / .transform / .transform3d / .css

Positioning strategy. Default is fixed left/top; the transform strategies translate instead; css writes custom properties and leaves applying them to your stylesheet

x-float:arrow

The arrow element: pinned to the edge facing the reference, rotated to point at it

$float

referenceEl (get/set), isPositioned, placement, side, alignment, matchSizeEnabled (get/set), updatePosition(), enableAutoUpdate(), disableAutoUpdate(), reset(), middleware (get/set)

This is the positioning layer under the overlay plugins: the modifiers you pass on x-popup:popup, x-popover:panel, x-menu:popup, and x-select:panel are these modifiers, forwarded. A falsey expression disables floating and resets the position. Gate the expression on visibility so the plugin only measures visible panels.

Examples

A basic float

Use x-float with the reference element as the expression, gated on visibility:

While the expression is falsey, the plugin doesn't calculate a position and $float.isPositioned stays false. Use it to hide the element until positioning finishes.

Choosing a side

Use a placement modifier with .offset to say where the element should sit:

Any Floating UI placement works: a side (top, right, bottom, left), optionally with an alignment (-start, -end). Leave the placement off and the plugin picks the side with the most space.

Staying in view

Use .flip, .shift, and .fit-y together so the element lands somewhere visible, with .pad for the distance from the boundary:

flip swaps to the opposite side when the preferred one is full, shift slides the element along the reference, and fit-y caps its height to what fits. This is the combination the custom-select snippet builds for its panel; core-popover uses flip.shift.update.pad.5px for tooltips that follow scrolling.

Matching the reference's size

Use .match to give the element the reference's width:

Dropdown panels use this to line up with their button. It is part of the default modifier string on x-select:panel. On a left or right placement, .match matches the height instead.

Reading the resolved placement

Use $float.placement, $float.side, and $float.alignment to style the element by where it actually landed:

With flip or auto, the requested side and the landed side can differ. The custom-select popup copies all three onto data- attributes so its open animation scales from the correct edge.

The css strategy

Use the css modifier when your stylesheet should decide whether the position applies:

Instead of writing inline styles, css sets --float-x and --float-y on the element (fit and match write --float-max-width, --float-max-height, --float-width, --float-height). The add-to-cart notification floats itself under the header cart button on desktop this way, while mobile ignores the variables and keeps its own layout.

Options from state

Pass an options object with getters for reactive values instead of a bare reference:

The hotspot tooltips pass their image container as rootBoundary, so flip and shift react to the edges of the image rather than the viewport. The expression is reactive: when a getter's state changes, the float updates.

Options

Option
What it does

referenceEl

The reference element (instead of a bare element expression)

strategy

'fixed', 'absolute', 'transform', 'transform3d', or 'css'

offset

Distance from the reference, in pixels

padding

Boundary padding for flip, shift, and fit

flip

Same as .flip

shift

true, 'cross', or 'both'

cover

Same as .cover

autoPlacement

true, 'x', or 'y'

fitX / fitY

Same as .fit-x / .fit-y

matchSize

Same as .match

autoUpdate

Same as .update

initialUpdate

Set false to skip positioning until told (the overlay plugins do this and call $float.enableAutoUpdate() on open)

rootBoundary

The Floating UI boundary that flip, shift, and fit respect (default 'viewport')

$float.middleware accepts an array of custom Floating UI middleware, which run after offset and before everything else. Most sections use x-popup or one of its child plugins instead. They set the reference, open state, and auto-update.

Last updated

Was this helpful?