Object Structures positionConfig

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, dxPopup, dxPopover, and dxToast).

The positionConfig 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|Object
Accepted Values: 'left' | 'right' | 'top' | 'bottom' | 'center' | 'left top' | 'left bottom' | 'right top' | 'right bottom'

The at option can take on an object containing the x and y fields, which specify horizontal and vertical position specifier respectively, or 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' };

boundary

The element within which the widget is positioned.

Type: Object

All collisions are computed against the element passed to this option. By default, widgets use the window object as a boundary element.

boundaryOffset

Specifies the horizontal and vertical offset from the window's boundaries.

Type: String|Object

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.

This option accepts an object containing the x and y fields which specify horizontal and vertical offset respectively, or 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' | 'flipfit' | 'none flip' | 'flip none' | 'none fit' | 'fit none' | 'none flipfit' | 'flipfit none' | 'flip fit' | 'fit flip' | 'fit flipfit' | 'flipfit 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
}

The available collision handler names are:

  • none
    Collisions do not affect 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.
  • flipfit
    Applies the fit collision handler after flip.
Show Example:
jQuery
<div class="button" data-bind="dxButton: { text: 'Show popup', onClick: showPopup }"></div>
<p style="text-align:center"><b>Position</b></p>
<div class="dx-fieldset">
  <div class="dx-field">
    <div class="dx-field-label">Collision</div>
    <div class="dx-field-value" data-bind="dxLookup: { dataSource: collisionValues, value: collisionValue }"></div>
  </div>
</div>
<div id="targetElement"></div>
<div id="myPopup" data-bind="dxPopup: {
    title: 'My Popup',
    visible: popupVisible,
    height: 150,
    width: 180,
    onClick: hidePopup,
    position: {
        my: 'top',
        at: 'bottom left',
        of: $('#targetElement'),
        collision: collisionValue()
    }
}">
      <p>The popup text.</p>
      <div class="button" data-bind="dxButton: { text: 'Hide popup', onClick: hidePopup }"></div>
</div>
popupVisible = ko.observable(false);
collisionValue = ko.observable("none");
showPopup = function () {
    popupVisible(true);
};
hidePopup = function () {
    popupVisible(false);
};
collisionValues = [
  "none",
  "none flip",
  "none fit",
  "flip",
  "flip none",
  "flip fit",
  "fit",
  "fit none",
  "fit flip"
];
body{
  text-align: center;
}
.button{
  margin: 10px;
}
#targetElement {
  margin-top: 40px;
  margin-right: 10%;
  display: inline-block;
  width: 70%;
  height: 50%;
  border-style: solid;
  background-color: lightgreen;
}

my

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

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

The my option can take on an object containing the x and y fields, which specify horizontal and vertical position specifier respectively, or 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') };

You can also pass a jQuery Event object to the of option. In this case, the element is positioned against the point whose coordinates equal event.pageX and event.pageY values.

HTML
<div id="myElement">. . .</div>
<div id="myPopover">
    <p>Popover content</p>
</div>
JavaScript
$("#myPopover").dxPopover({
    position: {
        my: "top",
        at: "bottom",
        of: "#myElement"
    }
});
$("#myElement").click(function(event){
    $("#myPopover").dxPopover("instance").option("position.of", event);
    $("#myPopover").dxPopover("instance").show();
})
Angular Approach
HTML
<div id="myElement" ng-click="processClick($event)">. . .</div>
<div data-bind="dxPopover: {
    position: {
        my: 'top',
        at: 'bottom',
        of: ofValue
    },
    bindingOptions: {
        visible: 'popoverVisible',
        'position.of': 'ofValue'
    }
}">
    <p>Popover content</p>
</div>
JavaScript
function Controller($scope) {
    $scope.popoverVisible = false;
    $scope.ofValue = "#myElement";
    $scope.processClick = function($event) {
        $scope.ofValue = event;
        $scope.popoverVisible = true;
    }
}
Knockout Approach
HTML
<div id="myElement" data-bind="click: processClick">. . .</div>
<div data-bind="dxPopover: {
    visible: popoverVisible,
    position: {
        my: 'top',
        at: 'bottom',
        of: ofValue
    }
}">
    <p>Popover content</p>
</div>
JavaScript
var viewModel = {
    popoverVisible: ko.observable(false),
    ofValue: ko.observable("#myElement"),
    processClick: function(data, event) {
        this.ofValue(event);
        this.popoverVisible(true);
    }
}

offset

Specifies horizontal and vertical offset in pixels.

Type: String|Object

This options accepts an object containing the x and y fields which specify the horizontal and vertical offset respectively, or a string consisting of hirizontal and vertical offset values separated separated by a space (e.g., "5 -10").

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