87 lines
3.3 KiB
Markdown
87 lines
3.3 KiB
Markdown
# LocalOverlayPositioning
|
|
|
|
## Featuring - [Popper.js](https://popper.js.org/)
|
|
|
|
Our local overlays use the open-source Popper.js library for positioning the content relative to the reference element, which we usually refer to as the invoker, in the context of local overlays.
|
|
|
|
## Features
|
|
|
|
- Everything Popper.js!
|
|
- Currently eagerly loads popper in the constructor of LocalOverlayController. Loading during idle time / using prefetch would be better, this is still WIP.
|
|
|
|
> Popper strictly is scoped on positioning. **It does not change the dimensions of the popper element nor the reference element**. This also means that if you use the arrow feature, you are in charge of styling it properly, use the x-placement attribute for this.
|
|
|
|
## How to use
|
|
|
|
For installation, see [LocalOverlayController](./LocalOverlayController.md)'s `How to use` section.
|
|
|
|
The API for LocalOverlay without Popper looks like this (`overlays` being the OverlayManager singleton):
|
|
|
|
```js
|
|
const localOverlay = overlays.add(
|
|
new LocalOverlayController({
|
|
contentTemplate: () =>
|
|
html`
|
|
<div class="demo-popup">United Kingdom</div>
|
|
`,
|
|
invokerTemplate: () =>
|
|
html`
|
|
<button @click=${() => popupController.toggle()}>UK</button>
|
|
`,
|
|
});
|
|
);
|
|
```
|
|
|
|
This will use the defaults we set for Popper configuration. To override the default options, you add a `popperConfig` object to the properties of the object you pass to `the LocalOverlayController` like so:
|
|
|
|
```js
|
|
const localOverlay = overlays.add(
|
|
new LocalOverlayController({
|
|
contentTemplate: () =>
|
|
html`
|
|
<div class="demo-popup">United Kingdom</div>
|
|
`,
|
|
invokerTemplate: () =>
|
|
html`
|
|
<button @click=${() => popupController.toggle()}>UK</button>
|
|
`,
|
|
popperConfig: {
|
|
/* Placement of popper element, relative to reference element */
|
|
placement: 'bottom-start',
|
|
positionFixed: true,
|
|
modifiers: {
|
|
/* Prevents detachment of content element from reference element */
|
|
keepTogether: {
|
|
enabled: true,
|
|
},
|
|
/* When enabled, adds shifting/sliding behavior on secondary axis */
|
|
preventOverflow: {
|
|
enabled: false,
|
|
boundariesElement: 'viewport',
|
|
/* When enabled, this is the <boundariesElement>-margin for the secondary axis */
|
|
padding: 32,
|
|
},
|
|
/* Use to adjust flipping behavior or constrain directions */
|
|
flip: {
|
|
boundariesElement: 'viewport',
|
|
/* <boundariesElement>-margin for flipping on primary axis */
|
|
padding: 16,
|
|
},
|
|
/* When enabled, adds an offset to either primary or secondary axis */
|
|
offset: {
|
|
enabled: true,
|
|
/* margin between popper and referenceElement */
|
|
offset: `0, 16px`,
|
|
},
|
|
},
|
|
},
|
|
});
|
|
);
|
|
```
|
|
|
|
The popperConfig is 1 to 1 aligned with Popper.js' API. For more detailed information and more advanced options, visit the [Popper.js documentation](https://popper.js.org/popper-documentation.html) to learn about the usage.
|
|
|
|
## Future additions
|
|
|
|
- Coming soon: Webcomponent implementation of LocalOverlay with a default arrow, styled out of the box to at least have proper rotations and positions.
|
|
- Default overflow and/or max-width behavior when content is too wide or high for the viewport.
|