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.

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
// Get the widget instance
...
showPopup = function() {
    popupInstance.show();
}
hidePopup = function() {
    popupInstance.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
// Get the widget instance
...
showPopup = function() {
    popupInstance.toggle(true);
}
hidePopup = function() {
    popupInstance.toggle(false);
}

Another way is to provide two-way binding for the visible option to show or hide the widget depending on the variable value. To show or hide the widget, assign true or false to the appropriate field respectively.

AngularJS Approach
JavaScript
function Controller($scope) {
    $scope.overlayVisible = false;
}
HTML
<div ng-controller="Controller">
    <div dx-overlay="{ bindingOptions: { 'visible': 'overlayVisible' }}"></div>
</div>
Knockout Approach
HTML
<div id="popupContainer" data-bind="dxPopup: {
     visible: popupVisible
}"></div>
JavaScript
var popupVisible = ko.observable(false);
var showPopup = function() {
    popupVisible(true);
}
var hidePopup = function() {
    popupVisible(false);
}

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
}

Hide The Widget Using The Back Button

An end-user can also hide the widget using the Back hardware button. To enable this feature, assign true to the closeOnBackButton option.

JavaScript
var overlayOptions = {
    closeOnBackButton: true
}

Specify a Widget Content

You can specify an overlay widget content using any of the following ways.

  • Insert the required markup into the widget container.

    HTML
    <div id="myPopover">
        <p>Popover content</p>
        <div id="hidePopoverButton"></div>
    </div>
    JavaScript
    $("#myPopover").dxPopover({
        showTitle: true,
        title: 'My Popover',
        onContentReady: function(){
            $("#hidePopoverButton").dxButton({
                text: "Hide popover",
                onClick: function(){
                    $("#myPopover").dxPopover("instance").hide();
                }
            })
        }
    });
    NOTE
    In the case of the jQuery approach, if an overlay widget contains other widgets, create them within a function handling the contentReady event as shown in the example above. Otherwise, inner widgets are not rendered.
    AngularJS Approach
    HTML
    <div ng-controller="Controller">
        <div dx-popover="{ 
            showTitle: true,
            title: 'My Popover',
            bindingOptions: { 'visible': 'popoverVisible' } 
        }">
            <p>Popover content</p>
            <div dx-button="{ text: 'Hide popover', onClick: hidePopover }}"></div>
        </div>
    </div>
    Knockout Approach
    HTML
    <div data-bind="dxPopover: {
        visible: popoverVisible,
        showTitle: true,
        title: 'My Popover',
    }">
        <p>Popover content</p>
        <div data-bind="dxButton: { text: 'Hide popover', onClick: hidePopover }}"></div>
    </div>
    See Also
  • Use the contentTemplate option to specify a template or rendering function used to render the widget content.

    HTML
    <div id="myPopover"></div>
    JavaScript
    $("#myPopover").dxPopover({
        showTitle: true,
        title: 'My Popover',
        contentTemplate: function(contentElement){
            contentElement.append("<p>Popover content</p>");
            var hidePopoverButton = $("<div>");
            contentElement.append(hidePopoverButton);
            hidePopoverButton.dxButton({
                text: 'Hide popover',
                onClick: function(){
                    $("#myPopover").dxPopover("instance").hide();
                }
            })
        }
    });
    AngularJS Approach
    HTML
    <div ng-controller="Controller">
        <div dx-popover="{ bindingOptions: { 'visible': 'popoverVisible' }, contentTemplate: 'popoverContent' }">
            <div data-options="dxTemplate: { name: 'title' }">
                <h1>My Popover</h1>
            </div>
            <div data-options="dxTemplate: { name: 'popoverContent' }">
                <p>Popover content</p>
                <div dx-button="{ text: 'Hide popover', onClick: hidePopover }}"></div>
            </div>
        </div>
    </div>
    Knockout Approach
    HTML
    <div data-bind="dxPopover: { visible: popoverVisible, contentTemplate: 'popoverContent' }">
        <div data-options="dxTemplate: { name: 'title' }">
            <h1>My Popover</h1>
        </div>
        <div data-options="dxTemplate: { name: 'popoverContent' }">
            <p>Popover content</p>
            <div data-bind="dxButton: { text: 'Hide popover', onClick: hidePopover }}"></div>
        </div>
    </div>
    See Also
  • Apply custom CSS styles to widget elements. For this purpose, assign a custom class name to the widget element and use this class name when defining styles for widget elements.

    HTML
    <div id="myPopup" class="custom-popup">
        Popup content
    </div>
    JavaScript
    $("#myPopover").dxPopup({
        visible: true,
        title: 'My Popup'
    });
    CSS
    .custom-popup .dx-popup-title {
        padding: 0px 10px;
    }
    .custom-popup .dx-popup-title .dx-toolbar-label {
        font-size: 12px;
        text-transform: uppercase;
    }
    .custom-popup .dx-popup-content {
        background: lightgray;
    }
    AngularJS Approach
    HTML
    <div ng-controller="Controller">
        <div dx-popup="{ bindingOptions: { visible: 'popupVisible' }, title: 'My Popup' }" class="custom-popup">
            Popup content
        </div>
    </div>
    CSS
    .custom-popup .dx-popup-title {
        padding: 0px 10px;
    }
    .custom-popup .dx-popup-title .dx-toolbar-label {
        font-size: 12px;
        text-transform: uppercase;
    }
    .custom-popup .dx-popup-content {
        background: lightgray;
    }
    Knockout Approach
    HTML
    <div data-bind="dxPopup: { visible: popupVisible, title: 'My Popup' }" class="custom-popup">
        Popup content
    </div>
    CSS
    .custom-popup .dx-popup-title {
        padding: 0px 10px;
    }
    .custom-popup .dx-popup-title .dx-toolbar-label {
        font-size: 12px;
        text-transform: uppercase;
    }
    .custom-popup .dx-popup-content {
        background: lightgray;
    }

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.

Specify a Widget Size

Overlay widgets enable you to specify their minimum and maximum size using the minWidth, minHeight, maxWidth and maxHeight options.

JavaScript
var myWidgetOptions = {
    minWidth: '20%',
    minHeight: '10%',
    maxWidth: '90%',
    maxHeight: '90%'
}

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 popupOptions = {
    shading: true,
    shadingColor: 'rgba(10, 100, 250, 0.4)'
}

Keyboard Support

An end-user can use the following keys to interact with an overlay.

  • Esc
    Hides the widget.

  • Up/down/left/right arrow
    Moves the widget if dragging is enabled.

List of Overlay Widgets

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

dxLoadPanel

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

View Demo

The widget supports common overlay widget functionality and enables you to carry out the following common tasks described at the beginning of this article.

In addition to common overlay functionality, the widget enables you to perform the following adjustments.

Specify the load panel appearance

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
}

Specify the display delay

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
}

Use a custom loading indicator

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

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

Show/hide the pane

The widget can display only the load indicator without the surrounding pane. This can help you 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 Lookup widget allows an end-user to select predefined values from a lookup window. Refer to the dxLookup guide for more information.

View Demo

dxPopover

The Popover widget is an overlay with an arrow that points to the UI element that has been clicked or tapped.

View Demo

The widget supports common overlay widget functionality and enables you to carry out the following common tasks described at the beginning of this article.

In addition to common overlay functionality, the widget enables you to perform the following adjustments.

Specify the target element

Use the target option to specify the UI element, which the widget points to.

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

Specify the widget title

You can specify whether or not the widget displays a title 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'
}

You can also specify a custom title appearance using the titleTemplate option.

See Also

dxPopup

The Popup widget is a popup window displaying specified content.

View Demo

The widget supports common overlay widget functionality and enables you to carry out the following common tasks described at the beginning of this article.

In addition to common overlay functionality, the widget enables you to perform the following adjustments.

Specify the widget title

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'
}

You can also specify a custom title appearance using the titleTemplate option.

See Also

Display top and bottom toolbars

You can also display top and bottom toolbars on the popup window. For this purpose, assign the appropriate array to the toolbarItems option. This option accepts an array of items that have the same structure as toolbar items. But in addition to toolbar item fields, the toolbarItems array item includes the toolbar field that specifies whether the item is displayed on a top or bottom toolbar. This field accepts the "top" and "bottom" values.

JavaScript
var popupOptions = {
    toolbarItems: [
        { toolbar: 'top', location: 'before', widget: 'dxButton', options: { type: 'back', text: 'Back' } },
        { toolbar: 'top', location: 'after', widget: 'dxButton', options: { icon: 'find' } },
        { toolbar: 'top', locateInMenu: 'always', text: 'Add' },
        { toolbar: 'bottom', location: 'before', widget: 'dxButton', options: { text: 'Load' } },
        { toolbar: 'bottom', location: 'before', widget: 'dxButton', options: { text: 'Save' } },
        { toolbar: 'bottom', location: 'before', widget: 'dxButton', options: { text: 'Clear' } }
    ]
}

dxToast

The Toast widget displays a toast with a specified message.

View Demo

The widget supports common overlay widget functionality and enables you to carry out the following common tasks described at the beginning of this article.

In addition to common overlay functionality, the widget enables you to perform the following adjustments.

Specify a message text

The message text is specified using the message option.

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

Hiding the toast

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

JavaScript
var toastOptions = {
    displayTime: 5000
}

An end-user can drag the toast away from the screen to hide it before the specified display time is elapsed. To disable this functionality, set the closeOnSwipe option to false.

In addition, the Toast widget includes the following options that can enable additional ways to hide the widget before the display time elapses.

  • closeOnBackButton
    Specifies whether or not the widget is closed if a user presses the Back hardware button.

  • closeOnClick
    Specifies whether or not the toast is closed if a user clicks it.

  • closeOnOutsideClick
    Specifies whether or not the widget is closed if a user clicks outside of it.

  • closeOnSwipe
    Specifies whether or not the toast is closed if a user swipes it out of the screen boundaries.

Specify the toast type

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 the 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 Tooltip widget displays a tooltip for the specified element.

View Demo

The widget supports common overlay widget functionality and enables you to carry out the following common tasks described at the beginning of this article.

In addition to common overlay functionality, the widget enables you to perform the following adjustments.

Specify the target 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 = document.getElementById('targetElement')
    }

Specify tooltip contents

The widget displays the elements located within its container tag.

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