# utils/dom/position

module

<a id="interfaces">

## Interfaces

<a id="interface-DomOptimalPositionOptions">

### `DomOptimalPositionOptions`

<a id="interface-DomPoint">

### `DomPoint`

<a id="interface-DomPositioningFunctionResult">

### `DomPositioningFunctionResult`

<a id="type-definitions">

## Type Definitions

<a id="typedef-PositioningFunction">

### `PositioningFunction`

<a id="functions">

## Functions

<a id="function-getConstrainedViewportRect">

### `getConstrainedViewportRect( viewportOffsetConfig = { viewportOffsetConfig.bottom?, viewportOffsetConfig.left?, viewportOffsetConfig.right?, viewportOffsetConfig.top? } ) → Rect`

Returns a viewport `Rect` shrunk by the viewport offset config from all sides.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-utils/src/dom/position.ts#L197)

#### Parameters

* `viewportOffsetConfig: object | undefined`

  Properties

  * `viewportOffsetConfig.bottom?: number`
  * `viewportOffsetConfig.left?: number`
  * `viewportOffsetConfig.right?: number`
  * `viewportOffsetConfig.top?: number`

#### Returns

* `Rect`

<a id="function-getOptimalPosition">

### `getOptimalPosition( options ) → DomPoint | null`

Calculates the `position: absolute` coordinates of a given element so it can be positioned with respect to the target in the visually most efficient way, taking various restrictions like viewport or limiter geometry into consideration.

**Note**: If there are no position coordinates found that meet the requirements (arguments of this helper), `null` is returned.

```typescript
// The element which is to be positioned.
const element = document.body.querySelector( '#toolbar' );

// A target to which the element is positioned relatively.
const target = document.body.querySelector( '#container' );

// Finding the optimal coordinates for the positioning.
const { left, top, name } = getOptimalPosition( {
	element: element,
	target: target,

	// The algorithm will chose among these positions to meet the requirements such
	// as "limiter" element or "fitInViewport", set below. The positions are considered
	// in the order of the array.
	positions: [
		//
	 	//	[ Target ]
		//	+-----------------+
		//	|	 Element	 |
		//	+-----------------+
		//
		targetRect => ( {
			top: targetRect.bottom,
			left: targetRect.left,
			name: 'mySouthEastPosition'
		} ),

		//
		//	+-----------------+
		//	|	 Element	 |
		//	+-----------------+
		//	[ Target ]
		//
		( targetRect, elementRect ) => ( {
			top: targetRect.top - elementRect.height,
			left: targetRect.left,
			name: 'myNorthEastPosition'
		} )
	],

	// Find a position such guarantees the element remains within visible boundaries of <body>.
	limiter: document.body,

	// Find a position such guarantees the element remains within visible boundaries of the browser viewport.
	fitInViewport: true
} );

// The best position which fits into document.body and the viewport. May be useful
// to set proper class on the `element`.
console.log( name ); // -> "myNorthEastPosition"

// Using the absolute coordinates which has been found to position the element
// as in the diagram depicting the "myNorthEastPosition" position.
element.style.top = top;
element.style.left = left;
```

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-utils/src/dom/position.ts#L116)

#### Parameters

* `options: DomOptimalPositionOptions`

  The input data and configuration of the helper.

#### Returns

* `DomPoint | null`

---

Full index of the CKEditor 5 API reference: [llms.txt](llms.txt)