Skip to main content

calculateOverlayPosition

calculateOverlayPosition is a utility function that calculates the position of an overlay element relative to a host element.

Import​

import { calculateOverlayPosition, GdOverlayPosition } from '@geodome/gdk/common';

Usage​

const position = calculateOverlayPosition(hostElement, targetElement, position, fixedPositioning, threshold);

Parameters​

Parameters
  • hostElement: HTMLElement
    • The anchor element to which the overlay is positioned relative to.
  • targetElement: HTMLElement
    • The overlay element to be positioned.
  • position: GdOverlayPosition
    • The desired position of the overlay relative to the host element.
  • fixedPositioning: boolean
    • Whether to use fixed positioning (true) or account for scroll position (false).
  • threshold: number (optional, default: 0)
    • The minimum distance to maintain between the overlay and the host element.
Returns
  • { left: number; top: number }: The calculated position of the overlay.

Description​

This function calculates the optimal position for an overlay element based on the host element's position, the desired placement, and viewport constraints. It ensures the overlay remains within the viewport and adjusts its position if necessary.

Positioning Options​

The GdOverlayPosition type offers the following positioning options:

type GdOverlayPosition =
'right-middle' | 'right-up' | 'right-down' |
'left-middle' | 'left-up' | 'left-down' |
'top-middle' | 'top-left' | 'top-right' |
'bottom-middle' | 'bottom-left' | 'bottom-right' |
'auto';

Position format: [position]-[direction]

  • First word: position relative to the anchor (right, left, top, bottom)
  • Second word: direction of expansion (middle, up, down, left, right)

Examples:

  • right-middle: Positions the overlay to the right of the host, vertically centered.
  • top-left: Positions the overlay above the host, aligned to the left.
  • bottom-right: Positions the overlay below the host, aligned to the right.
  • auto: Automatically chooses the best position based on available space.

Key Features​

  • Handles various positioning options
  • Adjusts for viewport boundaries
  • Supports fixed and absolute positioning
  • Provides a threshold for minimum distance between host and overlay
note

The function prioritizes keeping the overlay within the viewport, which may result in adjustments to the requested position if space is limited.