position

The position object specifies the widget positioning options.

Type: Object

This object is passed to the position configuration option of a widget that overlays the main screen (dxLoadPanel, dxOverlay, dxPopup, dxPopover, and dxToast).

The position object may contain the following fields: my, at, of, offset and collision. Look at the following sentence to see how to use these fields to position the required element against the target element.

"Place my 'left' side at the 'left bottom' corner of the '#targetElement'." The italic quoted phrase located after each option name within the sentence represents a value of the appropriate option.

at

The target element position that the widget is positioned against.

Type: String
Accepted Values: ['left'|'center'|'right'] ['top'|'center'|'bottom']

The at option can take on a string value consisting of horizontal and vertical position specifiers separated by a space (e.g., "left top"). The default value for each position specifier is "center". If you assign the "left" value to this option, it will be converted to the "left center" value.

JavaScript
position: { at: 'left bottom' };

boundaryOffset

A string value holding horizontal and vertical offset from the window's boundaries.

Type: String

This option is used to resolve collisions. If the specified offset from the specified target leads to a collision with the window's boundary, the boundaryOffset value is used to position the element near the place of collision.

Set a string in the following format: "5 -10", where the first number is a horizontal offset and the second number is a vertical offset in pixels.

collision

Specifies how to move the widget if it overflows the screen.

Type: String|Object
Accepted Values: ['none'|'flip'|'fit'] ['none'|'flip'|'fit']

A string passed to this option should contain a collision handler name, or a pair of names separated by space. If the string consists of a single collision handler name, it is applied to both horizontal and vertical axes. If you pass a pair of names separated by space, the first collision handler will be applied to the horizontal axis, the second to the vertical axis.

JavaScript
// a string containing horizontal and vertical
// collision handlers separated by space
collision: "flip fit";

You can also specify different collision handlers for horizontal and vertical axes in one of the following ways.

JavaScript
// an object containing 'x' and 'y' fields
collision: {
    x: "flip", // horizontal collision handler
    y: "none" // vertical collision handler
}

// an object containing 'h' and 'v' fields
collision: {
    h: "none", // horizontal collision handler
    v: "fit" // vertical collision handler
}

The available collision handler names are:

  • none
    Collisions do not affect the widget position.
  • flip
    Moves the widget to the opposite side of the target element if it allows more of the widget to be visible.
  • fit
    Shifts the widget from outside of the screen to fully display the widget.
Show Example:
jQuery

my

The position of the widget to align against the target element.

Type: String
Accepted Values: ['left'|'center'|'right'] ['top'|'center'|'bottom']

The my option can take on a string value consisting of horizontal and vertical position specifiers separated by a space (e.g., "left top"). The default value for each position specifier is "center". If you assign the "left" value to this option, it will be converted to the "left center" value.

JavaScript
position: { my: 'left' };

of

The target element that the widget is positioned against.

Type: Object

The option can take on one of the following values.

JavaScript
//CSS selector
position: { of: '#targetElement' };

//jQuery wrapper
position: { of: $('#targetElement') };

//DOM element
position: { of: document.getElementById('#targetElement') };

offset

A string value holding horizontal and vertical offset in pixels, separated by a space (e.g., "5 -10").

Type: String
JavaScript
position: { offset: '5 -10' };