offset

A middleware that offsets the floating element from its reference element.

Signature

function offset(
  value?: OffsetValue | OffsetFunction
): Middleware

type OffsetValue = number | OffsetOptions
type OffsetFunction = (args: OffsetFunctionArgs) => OffsetValue

interface OffsetOptions {
  mainAxis?: number
  crossAxis?: number
  alignmentAxis?: number | null
}

interface OffsetFunctionArgs {
  placement: Placement
  rects: ElementRects
  elements: Elements
}

Parameters

Parameter	Type	Description
value	number | OffsetOptions | OffsetFunction	Offset value, options object, or function returning either

OffsetOptions

Option	Type	Default	Description
mainAxis	number	0	Offset along the placement direction
crossAxis	number	0	Offset perpendicular to placement direction
alignmentAxis	number | null	null	Offset for aligned placements (overrides crossAxis)

Axis Directions

• Main axis: Direction of the placement (e.g., vertical for top/bottom)
• Cross axis: Perpendicular to the placement direction
• Alignment axis: Used for aligned placements like top-start, bottom-end

Examples

Numeric Offset

<script setup>
import { useFloating, offset } from 'v-float'

const context = useFloating(anchorEl, floatingEl, {
  middleware: [offset(10)]
})
</script>

Object Form

<script setup>
import { useFloating, offset } from 'v-float'

const context = useFloating(anchorEl, floatingEl, {
  middleware: [
    offset({ 
      mainAxis: 8,
      crossAxis: 4
    })
  ]
})
</script>

Alignment Axis

<script setup>
import { useFloating, offset } from 'v-float'

const context = useFloating(anchorEl, floatingEl, {
  placement: 'top-start',
  middleware: [
    offset({ 
      mainAxis: 8,
      alignmentAxis: 12
    })
  ]
})
</script>

Dynamic Offset

<script setup>
import { useFloating, offset } from 'v-float'

const context = useFloating(anchorEl, floatingEl, {
  middleware: [
    offset(({ placement, rects }) => {
      if (placement.startsWith('top')) {
        return 8
      }
      return { 
        mainAxis: rects.reference.height / 2,
        crossAxis: 4
      }
    })
  ]
})
</script>

See Also

• arrow - Often used with offset for arrow positioning
• flip - Flips placement when out of view
• shift - Shifts element to keep it in view