OOUI/Concepts

Certain core ideas or similar configuration options are shared by various elements/widgets that are not directly related.

This page documents some of them.

Overlays
Elements of certain widgets are positioned outside of normal flow, "on top of" everything else on the page, their dimensions constrained only by the browser viewport – for example, PopupButtonWidget's popup, or DropdownWidget's menu.

"ButtonsAndSwitchesPopupButtons1.png" "WidgetsSelectsAndOptionsDropdown1.png"

However, limitations of CSS occasionally prevent this. For example:


 * If the widget is placed inside a stacking context (other than the root one), created e.g. by using the  property, it is not possible to display the popup "on top of" content outside of that stacking context.
 * If the widget is placed inside a scrollable area, created by using the  property, it is not possible for the popup to extend outside of its dimensions.
 * Special case: if the widget is placed inside an OOUI dialog.

To avoid this, you can specify an "overlay" (using the  configuration option), inside of which the popup will be placed (instead of being inside of the widget). The overlay is a DOM element that should be outside of the affected area, allowing its contents to be positioned in the desired way.

In most cases, the overlay should be an element that is a direct child of the. (Using the body itself is also supported, but not recommended as it makes it harder to keep track of what inserted the popups there.) You can pass  to automatically create such an element via. For elements inside dialogs, you should use the dialog's  property.

Widgets and other elements supporting the  configuration option include:


 * PopupButtonWidget
 * LookupElement
 * CapsuleMultiselectWidget
 * ComboBoxInputWidget
 * DropdownWidget
 * FieldLayout
 * FieldsetLayout

Example
In this example, two nearly identical popup buttons are placed inside a dialog. The only difference is specifying an overlay or not. (Refer to OOUI/Windows/Dialogs and OOUI/Widgets/Buttons and Switches for more details about the boilerplate code.)



The first button's popup can't extend outside of the dialog's dimensions, only a small part of it is displayed and it requires scrolling to see the entire contents. The second button's popup can, and is displayed fully.