offset
offset()
displaces the floating element from its core
placement
along the specified axes.
0px
10px
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.