Overlay Widgets

This article describes the common principles behind widgets comprised of various pop-up UI elements, such as a dialog, menu, toast message, etc.

Common Tasks

When working with an overlay widget, you can often encounter tasks common for all overlays. This section describes the most important common tasks such as controlling widget visibility, positioning the widget, adjusting animation options, etc.

Control The Widget Visibility

One of the frequently encountered tasks when working with an overlay widget is controlling widget visibility. You can use any of the following approaches to control widget visibility.

jQuery Approach

All widgets include the show() and hide() methods, which show and hide the widget respectively. To access a widget method, obtain the widget instance first.

JavaScript
showOverlay = function() {
    var overlay = $("#overlayContainer").dxOverlay("instance");
    overlay.show();
}
hideOverlay = function() {
    var overlay = $("#overlayContainer").dxOverlay("instance");
    overlay.hide();
}

You can also change widget visibility using the toggle(showing) method, which displays or hides the widget depending on the value of the showing parameter.

JavaScript
showOverlay = function() {
    var overlay = $("#overlayContainer").dxOverlay("instance");
    overlay.toggle(true);
}
hideOverlay = function() {
    var overlay = $("#overlayContainer").dxOverlay("instance");
    overlay.toggle(false);
}

Knockout Approach

If you use the Knockout approach, you can pass an observable variable to the visible option to show or hide the widget depending on the variable value.

JavaScript
var overlayVisible = ko.observable(false);
var showOverlay = function() {
    overlayVisible(true);
}
var hideOverlay = function() {
    overlayVisible(false);
}

Angular Approach

Widget visibility in the Angular approach is controlled using a $scope object field associated with the visible configuration option of the widget. To associate a $scope object field with the visible option, provide two-way binding between them as illustrated in the following example.

JavaScript
function Controller($scope) {
    $scope.overlayVisible = false;
}
HTML
<div ng-controller="Controller">
    <div dx-overlay="{ bindingOptions: { 'visible': 'overlayVisible' }}"></div>
</div>

To show or hide the widget, assign true or false to the appropriate field respectively.

Hide The Widget on Outside Click

To hide the window when an end-user clicks outside of it, set the closeOnOutsideClick option to true.

JavaScript
var overlayOptions = {
    closeOnOutsideClick: true
}

Position a Widget

You can position an overlay widget against the required element if your needs dictate so. The positioning options are accessed using the position configuration option.

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 widget against the target element.

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

JavaScript
var overlayOptions = {
    position: {
        my: 'left top',
        at: 'left',
        of: '#targetElement'
    }
}

For the detailed description of positioning options, refer to the position object structure description.

Adjust Animation Options

An overlay widget enables you to adjust animation effects used when the widget is being shown or hidden. The animation options are accessed using the animation configuration option. The animation configuration object includes separate properties that hold animation options used when the widget is being shown and hidden. These properties are called show and hide respectively. Objects passed to these properties have the same structure, which enables you to specify the following main options.

  • Animation type
    The animation type is specified using the type option. The available types are "fade", "pop" and "slide".

  • Initial and target state
    The widget state at the beginning of animation is specified using the from option. The to option specifies the target widget state.

JavaScript
var overlayOptions = {
    animation: {
        show: {
            type: 'pop',
            duration: 1000,
            from: {
                opacity: 0,
                scale: 0
            }
            to: {
                opacity: 1,
                scale: 1
            }
        }
        hide: {
            type: 'pop',
            duration: 1000,
            from: {
                opacity: 1,
                scale: 1
            }
            to: {
                opacity: 0,
                scale: 0
            }
        }
    }
}

For a full list of animation options and their detailed descriptions, refer to the animation object structure description.

Display Modes

Some overlay widgets support the full-screen mode, which allows you to stretch the widget on the full screen. To enable this mode, set the fullScreen option of the widget to true.

JavaScript
var popupOptions = {
    fullScreen: true
}

An overlay widget can also shade the main screen when the widget is visible. To enable shading, set the shading option of the widget to true. You can also specify the shading color using the shadingColor option.

JavaScript
var overlayOptions = {
    shading: true,
    shadingColor: 'rgba(10, 100, 250, 0.4)'
}">

List of Overlay Widgets

The following DevExtreme UI widgets are related to the overlays category.

dxOverlay

The dxOverlay widget is a base widget for other overlay widgets. Thus, it only supports the common functions described above.

NOTE
The dxOverlay widget does not support the fullScreen option because it displays custom content whose size depends on the style settings applied to this content.

dxLoadPanel

The dxLoadPanel widget is an overlaying element indicating that loading is in progress.

You can specify the message displayed by the load panel using the message option.

By default the widget displays a load indicator that looks like a turning circle in addition to the specified message. You can assign false to the showIndicator option to disable the load indicator which can help to avoid problems with animation on a slow device.

JavaScript
var loadPanelOptions = {
    message: "Loading...",
    showIndicator: false
}

You can display the load panel immediately after a loading process has been started or after the delay specified by the delay option.

JavaScript
var loadPanelOptions = {
    message: "Loading...",
    delay: 1000
}

If you need to use a custom image instead the standard indicator icon, you should specify the required image URL using the indicatorSrc option.

JavaScript
var loadPanelOptions = {
    message: "Loading...",
    indicatorSrc: "images/indicator.png"
}

The widget can display only the load indicator without the surrounding pane. This can help avoid the use of excess visual elements when indicating the loading process. Set the showPane option to false to hide the pane.

JavaScript
var loadPanelOptions = {
    showPane: false
}

dxLookup

The dxLookup widget allows an end-user to select predefined values from a lookup window. Refer to the dxLookup guide for more information.

dxPopover

The dxPopover widget is an overlay with an arrow that points to the UI element that has been clicked or tapped. Use the target option to specify the UI element, which the widget points to.

JavaScript
var popoverOptions = {
    target: "#targetButton"
}

You can specify whether the widget displays a title or not using the showTitle option. If this option is enabled, specify the title text using the title option.

JavaScript
var popoverOptions = {
    showTitle: true,
    title: 'Popover title'
}

If you use the MVVM approach (Knockout or Angular), you can define the title template and assign its name to the titleTemplate option to specify the custom title structure.

HTML
<div data-bind="dxPopover: { titleTemplate: 'popoverTitle' }">
    <div data-options="dxTemplate: { name: 'popoverTitle' }">
        <p>Title: "<b data-bind="text: $data.title"></b>"</p>
    </div>
</div>
JavaScript
var viewModel = {
    textTitle: "Popover Title"
}
ko.applyBindings(viewModel);

dxPopup

The dxPopup widget is a popup window displaying the specified content. You can specify whether the widget displays a title or not using the showTitle option. If this option is enabled, specify the title text using the title option.

JavaScript
var popupOptions = {
    showTitle: true,
    title: 'Popup title'
}

If you use the MVVM approach (Knockout or Angular), you can define the title template and assign its name to the titleTemplate option to specify the custom title structure.

HTML
<div data-bind="dxPopup: { titleTemplate: 'popupTitle' }">
    <div data-options="dxTemplate: { name: 'popupTitle' }">
        <p>Title: "<b data-bind="text: $data.title"></b>"</p>
    </div>
</div>
JavaScript
var viewModel = {
    textTitle: "Popup Title"
}
ko.applyBindings(viewModel);

dxToast

The dxToast widget displays a toast with the message whose text is specified using the message option.

JavaScript
var toastOptions = {
    message: "Toast is displayed"
}

By default the toast message disappears after 2 seconds. You can change this behavior using the displayTime option, which specified the display time in milliseconds.

JavaScript
var toastOptions = {
    displayTime: 5000
}

You can also specify the toast type using the type option, which takes on one of the following values: "info", "warning", "error", "success" and "custom". This option affects the toast color and the icon displayed in the message.

JavaScript
var toastOptions = {
    type: "info"
}

The "custom" type enables you to specify a custom toast appearance. In this case, the toast will display contents of the widget container element.

HTML
<div id="toastContainer">
    <p>Custom toast message</p>
    <div class="dx-icon dx-icon-toolbox"></div>
</div>

dxTooltip

The dxTooltip widget displays a tooltip for the specified element. Use the target option to specify the element for which the tooltip should be displayed. You can specify the target element in any of the following ways.

  • CSS selector

    JavaScript
    var tooltipOptions = {
        target = '#targetElement'
    }
  • jQuery wrapper

    JavaScript
    var tooltipOptions = {
        target = '#targetElement'
    }
  • DOM element

    JavaScript
    var tooltipOptions = {
        target = '#targetElement'
    }

The widget displays the elements located within its container tag.

HTML
<div id="tooltip">
    <p>Tooltip content</p>
</div>