offset

offset() displaces the floating element from its core placement along the specified axes.

Usage

import {computePosition, offset} from '@floating-ui/dom';
 
computePosition(referenceEl, floatingEl, {
  middleware: [offset(10)],
});

The value(s) passed are logical, meaning their effect on the physical result is dependent on the writing direction (e.g. RTL).

Order

offset() should generally be placed at the beginning of your middleware array.

Options

These are the options you can pass to offset().

interface AxesOffsets {
  mainAxis?: number;
  crossAxis?: number;
  alignmentAxis?: number | null;
}
 
type Options =
  | number
  | AxesOffsets
  | (({
      reference: Rect,
      floating: Rect,
      placement: Placement,
    }) => number | AxesOffsets);

A number represents the distance (gutter or margin) between the floating element and the reference element. This is shorthand for mainAxis.

offset(10);

AxesOffsets

This is an object which enables you to individually configure each axis.

mainAxis

default: 0

Represents the distance (gutter or margin) between the floating element and the reference element.

offset({mainAxis: 10});

crossAxis

default: 0

Represents the skidding between the floating element and the reference element.

offset({crossAxis: 10});

alignmentAxis

default: null

Works on the same axis as crossAxis but applies only to aligned placements and works logically. The offset is inverted for -end alignments.

This will override the crossAxis offset when set to a number.

offset({alignmentAxis: 10});

Function

You may also pass a function which returns the previously listed values — this enables you to read the dimensions of the reference or floating elements and the current placement.

offset(({rects, placement}) =>
  placement === 'bottom'
    ? rects.floating.width
    : rects.reference.width
);
 
offset(({rects, placement}) => ({
  mainAxis: placement === 'top' ? 5 : -5,
  crossAxis:
    placement === 'right'
      ? rects.reference.width
      : rects.floating.width,
}));

Negative values

Using the function technique above in combination with negative values enables the ability to "inset" the floating element such that it is positioned on top of the reference element in some fashion.

This is useful for UI components such as select dropdowns where it should be positioned relative to an item inside the dropdown list.