useFloatingUI
A thin wrapper around Floating UI for positioning a floating element, such as a tooltip, dropdown, or popover, against its anchor.
useFloatingUI or Anchor?
Use this hook when you are writing your own impulse element that opens and closes a floating element. If you only need something positioned from markup, use the Anchor component instead. Both share the same positioning logic and defaults.
Usage
import { ImpulseElement, registerElement, target } from '@ambiki/impulse';
import { useFloatingUI } from '@ambiki/impulse-view-components/hooks';
@registerElement('pop-over')
export default class PopoverElement extends ImpulseElement {
// The anchor.
@target() button: HTMLButtonElement;
// The floating element, positioned against the anchor.
@target() panel: HTMLElement;
private floatingUI: ReturnType<typeof useFloatingUI>;
connected() {
this.floatingUI = useFloatingUI(this, {
anchorElement: this.button,
floatingElement: this.panel,
placement: 'bottom',
});
}
show() {
// Show the popover.
this.panel.hidden = false;
// Start positioning logic.
this.floatingUI.start();
}
async hide() {
// Hide the popover.
this.panel.hidden = true;
// Stop positioning logic.
await this.floatingUI.stop();
}
// Repositioning does nothing while this is `false`.
get open() {
return !this.panel.hasAttribute('hidden');
}
}Arguments
useFloatingUI(element, options);element
| Name | Default | Description |
|---|---|---|
| element | N/A | The impulse element (usually this), with an open property. The hook stops when the element disconnects. |
options
Either an object, or a function that returns one. An object is read once, when the hook is created. A function is called every time the floatingElement is repositioned, so options that change while it's open (such as a placement attribute) are picked up on the next reposition. Call the returned update() to reposition straight away.
start() keeps following the anchorElement and floatingElement it found when it was called. If the function returns different elements later, call stop() and then start() to follow the new ones.
this.floatingUI = useFloatingUI(this, () => ({
anchorElement: this.button,
floatingElement: this.panel,
placement: this.placement,
}));| Name | Default | Description |
|---|---|---|
| anchorElement | N/A | The element (or a virtual element, such as a pointer position) to position against. |
| floatingElement | N/A | The element to position against the anchorElement. |
| arrowElement | undefined | An element inside the floatingElement that points at the anchorElement. |
| arrowPadding | 0 | The padding in pixels between the arrow and the edges of the floatingElement. |
| middleware | [] | Array of Floating UI middleware for fine-grained positioning control. They run after the built-in middleware and before the arrow is aligned. Read the docs. |
| offsetOptions | 0 | Adds distance between the anchorElement and the floatingElement. Read the docs. |
| placement | bottom | The preferred placement of the floatingElement. The actual placement may vary to keep it inside the viewport. One of top, top-start, top-end, right, right-start, right-end, bottom, bottom-start, bottom-end, left, left-start, or left-end. Read the docs. |
| flipOptions | undefined | Options for flipping the floatingElement to another placement when the preferred one doesn't fit. Flipping is always on. Read the docs. |
| keepFlipped | false | Keeps the side the floatingElement flipped to until stop() is called, instead of trying placement first on every reposition, so it doesn't jump back once its content shrinks. It still flips again when that side stops fitting. |
| shiftOptions | undefined | Options for shifting the floatingElement along the anchorElement to keep it inside the viewport. Shifting is always on. Read the docs. |
| strategy | fixed | The value of the position CSS property. One of absolute or fixed. |
| sync | undefined | Matches the floatingElement's size to the anchorElement's. One of height, width, or both. |
| autoSize | undefined | Exposes the space available to the floatingElement as the --awc-auto-size-height and --awc-auto-size-width CSS custom properties. One of height, width, or both. A floatingElement capped to that space flips when it is squashed and the other side has more room. |
| autoSizePadding | 0 | The padding in pixels to keep from the viewport edge when measuring the available space. |
Returns
The hook places the floatingElement once when it's created. After that, repositioning does nothing while open is false. It returns:
| Name | Description |
|---|---|
start() | Starts positioning the floatingElement, and keeps it next to the anchorElement as the page scrolls or resizes. |
update() | Repositions the floatingElement straight away. Returns a promise. Does nothing while open is false. |
stop() | Stops positioning. The floatingElement stays where it was last placed. Returns a promise that resolves once it has stopped, on the next frame if it was running. |