OverlayController has many configuration options.
Using different combinations of those properties, different components like a tooltip, popover, dialog etc. can be made.
OverlayMixin exposes these options via
This determines the DOM position of the
contentNode, either next to the invokerNode,
or in the
global-overlays container at the bottom of the
As specified in the overlay rationale there are only two official types of overlays: dialogs and tooltips. And their main differences are:
- Dialogs have a modal option, tooltips don’t
- Dialogs have interactive content, tooltips don’t
- Dialogs are opened via regular buttons (click/space/enter), tooltips act on focus/mouseover
Since most overlays have interactive content the default is set to dialogs. To get a tooltip, you can add
isTooltip to the config object. This only works for local placement and it also needs to have
handlesAccessibility activated to work.
Boolean property. When true, the focus will rotate through the focusable elements inside the
For Modal Dialogs this is an important feature, since these are considered "their own page", so especially from an accessibility point of view, trapping the focus inside the dialog is crucial.
You use the feature on any type of overlay.
Boolean property. Will allow closing the overlay on ESC key when enabled.
Boolean property. Will allow closing the overlay by clicking outside the
.focus() the HTMLElement passed to this property. By default, this is the
In the example, we focus the body instead of the
Boolean property. When true, will add a backdrop when the overlay is opened.
Backdrops will overlay each other if you open nested overlays with enabled backdrops. If this is not what you intend, you can make the overlays not nested, where opening one, closes the other. Fortunately, we also have a configuration option that simulates that behavior in the next section
The backdrop styling can be configured by targeting the
.global-overlays .global-overlays__backdrop css selector.
The backdrop animation can be configured by targeting the
.global-overlays .global-overlays__backdrop--animation-in and
.global-overlays .global-overlays__backdrop--animation-out css selector.
This currently only supports CSS Animations, because it relies on the
animationend event to add/remove classes.
Boolean property. When true, will block other overlays.
This example shows nested overlays, but they don't have to be. For example, they could be siblings, or completely unrelated.
When an overlay with
isBlocking is opened, all other overlays are hidden by the
OverlaysManager, which, as a global registry, is aware of all active overlays on the page.
Boolean property. When true, prevents scrolling content that is outside of the
Determines where the overlay is placed relative to the viewport. This can only be used in combination with a 'global'
For locally DOM positioned overlays that position themselves relative to their invoker, we use Popper.js for positioning.
contentNodeis often referred to as
invokerNodeis often referred to as the
- Everything Popper features!
- Currently eagerly loads popper if mode is local, in the constructor. Loading during idle time / using prefetch would be better, this is still WIP. PRs are welcome!
Popper strictly is scoped on positioning. It does not change the dimensions of the content node nor the invoker node. This also means that if you use the arrow feature, you are in charge of styling it properly, use the data-popper-placement attribute for this. An example implementation can be found in lion-tooltip, where an arrow is set by default.
To override the default options we set for local mode, you add a
popperConfig object to the config passed to the OverlayController.
Here's a succinct overview of some often used popper properties:
Note: popperConfig reflects Popper API