TURBO for Developers

Home > widget-integration > PositionService

PositionService class

Service for calculating ISW dropdown position.

Technical Support teams can extend this service for custom positioning:

Signature:

export declare class PositionService

Example

window.boostWidgetIntegration.extend('PositionService', (PositionService) => {
  return class CustomPositionService extends PositionService {
    // Add custom offset for a specific theme
    protected getGap() {
      return window.myThemeConfig?.iswGap || super.getGap();
    }
  };
});

Constructors

Constructor	Modifiers	Description
(constructor)(appService)		Constructs a new instance of the `PositionService` class

Properties

Property	Modifiers	Type	Description
appService	`protected`	AppService
BORDER	`protected` `readonly`	(not declared)	Border width compensation
BOTTOM_MARGIN	`protected` `readonly`	(not declared)	Bottom margin for viewport calculation
DEFAULT_Z_INDEX	`protected` `readonly`	(not declared)	Default z-index for dropdown
GAP	`protected` `readonly`	(not declared)	Gap between input and dropdown
HEADER_OVERLAP_Z_INDEX	`protected` `readonly`	(not declared)	Reduced z-index when below header
SCROLL_DEBOUNCE_MS	`protected` `readonly`	(not declared)	Scroll debounce delay in ms

Methods

Method	Modifiers	Description
applyMaxHeightToResults(container, maxHeight)		Apply max height to the results container inside the dropdown.
applyPosition(element, config)		Apply position styles to an element.
calculateBodyPosition(rect, searchSettings)	`protected`	Calculate position when ISW is appended to body.
calculateDialogPosition(rect, searchSettings)	`protected`	Calculate position when ISW is inside a dialog.
calculateMaxHeight(searchSettings, availableHeight)		Calculate maximum height for the dropdown. Legacy: calcMaxHeightByStyle - Hard-coded values based on style New: Configurable with style-specific constraints and suggestionMaxHeight support
calculatePosition(input, searchSettings)		Calculate dropdown position relative to the input element. Legacy: calcPositionSuggestionResult(context, input) - inline calculation New: Separated service with configurable offsets
calculateScrollZIndex()	`protected`	Calculate z-index based on scroll position relative to header. When the search form scrolls behind the header, reduce z-index to prevent overlap issues.
calculateWidth(input, searchSettings)		Calculate suggested dropdown width based on input element.
cleanupScrollHandler()		Clean up scroll handler.
dispose()		Cleanup all resources.
getBorder()	`protected`	Get border width compensation. Override for themes with different borders.
getContainerElement()		Get the ISW container element for the current device.
getGap()	`protected`	Get gap between input and dropdown. Override for custom spacing.
isInDialog(element)		Check if an element is inside a dialog.
isISWInDialog()		Check if ISW element has been moved to dialog.
isMobileDevice()	`protected`	Check if current device is mobile or tablet (≤ 991 px). Matches the legacy `isMobile(isTabletPortraitMax)` threshold so that tablets are positioned with the mobile ISW container, consistent with the full-width style determination in InstantSearchSelectors.
isRightAligned(rect)	`protected`	Determine if dropdown should be right-aligned.
isStyleFullWidth(searchSettings)		Check if the current style is full width. Legacy: isStyleFullWidth(context) New: Single authoritative method — delegates from InstantSearchSelectors
log(message, data)	`protected`	Log debug messages when debug mode is enabled.
setDebugMode(enabled)		Enable or disable debug logging.
setupScrollHandler(container)		Set up scroll handler to adjust z-index when scrolling. Legacy: Inline scroll handler with debounce in calcPositionSuggestionResult New: Dedicated method with proper cleanup
updatePosition(input, container, searchSettings)		Full position update flow: calculate, apply, and setup scroll handler.

← Back to Library Reference