CKEditor Ecosystem Documentation
Search
Home/CKEditor 5/API
Typedef

positioningFunction (utils/dom)

@ckeditor/ckeditor5-utils/src/dom/position

typedef
function
See source

A positioning function which, based on positioned element and target Rects, returns rect coordinates representing the geometrical relation between them. Used by the getOptimalPosition helper.

// This simple position will place the element directly under the target, in the middle:
//
//	    [ Target ]
//	+-----------------+
//	|     Element     |
//	+-----------------+
//
const position = ( targetRect, elementRect, [ viewportRect ] ) => ( {
	top: targetRect.bottom,
	left: targetRect.left + targetRect.width / 2 - elementRect.width / 2,
	name: 'bottomMiddle',

	// Note: The config is optional.
	config: {
		zIndex: '999'
	}
} );

Filtering

Parameters

elementRect : Rect

The rect of the element to be positioned.

targetRect : Rect

The rect of the target the element (its rect) is relatively positioned to.

viewportRect : Rect

The rect of the visual browser viewport.

Returns

Object | null

return When the function returns null, it will not be considered by getOptimalPosition.

Number

return.top The top value of the element rect that would represent the position.

Number

return.left The left value of the element rect that would represent the position.

Number

return.name The name of the position. It helps the user of the getOptimalPosition helper to recognize different positioning function results. It will pass through to the Position returned by the helper.

Number

[return.config] An optional configuration that will pass-through the getOptimalPosition helper to the Position returned by this helper. This configuration may, for instance, let the user of getOptimalPosition know that this particular position comes with a certain presentation.