https://github.com/polymerlabs/iron-overlay
Overlay element that overcomes the stacking context trap
https://github.com/polymerlabs/iron-overlay
Last synced: 3 months ago
JSON representation
Overlay element that overcomes the stacking context trap
- Host: GitHub
- URL: https://github.com/polymerlabs/iron-overlay
- Owner: PolymerLabs
- Created: 2016-09-09T17:58:56.000Z (almost 10 years ago)
- Default Branch: master
- Last Pushed: 2017-12-20T12:57:35.000Z (over 8 years ago)
- Last Synced: 2025-04-09T01:27:20.485Z (about 1 year ago)
- Language: HTML
- Homepage:
- Size: 146 KB
- Stars: 13
- Watchers: 18
- Forks: 3
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
[](https://travis-ci.org/PolymerLabs/iron-overlay)
## The problem
Overlays should always render on the top layer. This is achieved using the css
properties `position: fixed` and `z-index`. When an overlay is contained in a node
that creates a new [stacking context](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Positioning/Understanding_z_index/The_stacking_context),
it causes the overlay to be trapped within it (z-index and position will be relative to
the new stacking context), resulting in problems like [this one](http://jsbin.com/kuboqa/1/edit?html,output):
```html
.backdrop {
position: fixed;
top: 0; bottom: 0;
left: 0; right: 0;
z-index: 100;
background-color: rgba(0, 0, 0, 0.5);
}
.overlay {
position: fixed;
z-index: 999;
}
```
`iron-overlay` works around this issue by "teleporting" its content to a
stacking-context-safe node.
```html
Open overlay
This text will be stamped and appended to the document body.
```
## iron-overlay
It delegates rendering of the overlay content to a renderer (`iron-overlay-renderer`).
It won't host the renderer, but request another element to host it through the
events `iron-overlay-attach` and `iron-overlay-detach`, or append it to ``.
It requires overlay contents to be contained in a `` (since they need
to be hosted in the renderer).
## iron-overlay-renderer
Takes care of the rendering (e.g. center overlay), and handles the switch from
opened state to closed state & viceversa.
## iron-overlay-container
Hosts the overlay renderers, keeps track of the opened overlays. This element should
be placed in a stacking-context safe node (e.g. `document.body`).
```html
Open overlay
This text will be contained in iron-overlay-content
```
## Styling
Styling must be done in the context of where iron-overlay will be hosted.
### Styling the renderer
`iron-overlay` sets the renderer's `data-overlay` attribute to be its id, so
that styling of the overlay can be done like this:
```html
[data-overlay] {
--iron-overlay-background-color: yellow;
}
[data-overlay="overlay1"] {
--iron-overlay-background-color: orange;
}
Overlay Content
Overlay 1 Content
```
### Styling the content
Content can be styled by passing a `` element into the template,
but beware of possible conflicts with classes, as selectors will apply to all
matching elements in the styling context where they're hosted:
```html
<iron-overlay>
<template>
<style>
.my-content {
background-color: yellow;
}
Content
Other Content
```
The best approach to ensure style encapsulation is to create a custom element
for your content.
```html
Content
Other Content
```