Overview

#

A composable that manages the positioning of floating elements such as tooltips and dropdown menus relative to their anchor elements. It is built with Floating UI.

Some design system components use it internally, but it can also be used independently, typically (but not necessarily) together with useKFloatingInteraction.

See Floating elements .

Floating UI version updates

#

Usage

#

initPosition

Positions a floating element relative to the anchor element and sets up auto-updating so the position stays correct on scroll, resize, etc. To be called when the floating element is shown or added to the DOM. See Options .

      import useKFloatingPosition from 'kolibri-design-system/lib/composables/useKFloatingPosition';

      const { initPosition } = useKFloatingPosition();

      initPosition(
        'my-tooltip',            // Unique ID of the floating element
        floatingEl,              // Floating DOM element (e.g. tooltip)
        anchorEl,                // Anchor DOM element (e.g. button)
        options                  // Floating UI options
      );
    

destroyPosition

Stops auto-updating the position of the floating element positioned with initPosition. Call when the floating element is hidden or removed from the DOM to prevent severe performance problems.

      import useKFloatingPosition from 'kolibri-design-system/lib/composables/useKFloatingPosition';

      const { destroyPosition } = useKFloatingPosition();

      destroyPosition('my-tooltip');
    

Options

The options object passed to initPosition corresponds to the options parameter of Floating UI's computePosition. Use options to configure placement, strategy, and middleware. Middleware can be imported from useKFloatingPosition.

      import useKFloatingPosition from 'kolibri-design-system/lib/composables/useKFloatingPosition';

      const { initPosition, offset, flip, shift } = useKFloatingPosition();

      initPosition('my-tooltip', floatingEl, anchorEl, {
        placement: 'bottom',
        strategy: 'fixed',
        middleware: [
          offset(6),
          flip(),
          shift({padding: 5}),
        ],
      });
    

Custom implementation

initPosition and destroyPosition are designed to work seamlessly with other parts of the design system and cover the majority of use cases. In rare cases, it may be useful to have direct access to Floating UI, for example when you only need the x, y coordinates and want to apply them yourself. You can import Floating UI functions from useKFloatingPosition and use them as described in the Floating UI documentation.

      import useKFloatingPosition from 'kolibri-design-system/lib/composables/useKFloatingPosition';

      const { computePosition, autoUpdate } = useKFloatingPosition();
    

Example

#

Click the button to toggle the tooltip.

Related

#

• Floating elements has general overview of floating elements
• useKFloatingInteraction TBD
• Floating UI