# ef-overlay

Element to help building modals, dialogs and other overlay content

## Properties

| Property                          | Attribute                    | Type                                | Default | Description                                      |
|-----------------------------------|------------------------------|-------------------------------------|---------|--------------------------------------------------|
| `focusBoundary`                   |                              | `HTMLElement \| ShadowRoot \| null` | "this"  | Set focus boundary to restrict tabbing. Default's overlay itself.<br />If external focus is required, set to null |
| `fullScreen`                      | `full-screen`                | `boolean`                           | false   | Set to true to show overlay in full screen mode  |
| `fullyOpened (readonly)`          |                              | `boolean`                           | false   | Returns true if the overlay is opened and animation is not running.<br />Returns false if overlay is closed and animation is not running |
| `horizontalOffset`                | `horizontal-offset`          | `number`                            | 0       | A pixel value that will be added to the position calculated on the horizontal axis.<br />The offset will be applied either to the `left` or `right` depending on the `positionTarget` |
| `interactiveElements`             |                              | `HTMLElement[]`                     | []      | A list of elements, which are active when overlay is opened<br />Valid only if noInteractionLock is false (default) |
| `lockPositionTarget`              | `lock-position-target`       | `boolean`                           | false   | True to lock position target<br />Valid only if noInteractionLock is false (default) |
| `noAutofocus`                     | `no-autofocus`               | `boolean`                           | false   | Set to true to disable autofocusing the overlay or open |
| `noCancelOnEscKey`                | `no-cancel-on-esc-key`       | `boolean`                           | false   | Set to true to disable canceling the overlay with the ESC key |
| `noCancelOnOutsideClick`          | `no-cancel-on-outside-click` | `boolean`                           | false   | Set to true to disable canceling the overlay by clicking outside it |
| `noFocusManagement`               | `no-focus-management`        | `boolean`                           | false   | True to not apply focus management.<br />The overlay will not limit Tab behaviour or do auto-focusing |
| `noInteractionLock`               | `no-interaction-lock`        | `boolean`                           | false   | Stop preventing user interaction when overlay is visible |
| `noOverlap`                       | `no-overlap`                 | `boolean`                           | false   | True to not overlap positionTarget               |
| `offset`                          | `offset`                     | `number`                            | 0       | A pixel value that will be added to the position calculated on the vertical or horizontal axis.<br />The offset is applied dynamically depending on the `positionTarget` |
| `opened`                          | `opened`                     | `boolean`                           | false   | True if the overlay is currently displayed       |
| `position`                        | `position`                   | `Position[] \| undefined`           |         | Set position and align against the attach target.<br />Position may contain a single word or a comma separated list to set the priority.<br />Position is not applied if `positionTarget` is not an HTML Element.<br />For instance: `bottom-middle, top-middle` - default position is `bottom-middle`, if cannot fit then position would be `top-middle`;<br />or `left, right` - align is not set, set best position on the `left` or `right`<br /><br />Position can be: `top`, `right`, `bottom`, `left`, `center`<br />Align can be: `start`, `middle`, `end` |
| `positionTarget`                  | `position-target`            | `PositionTarget\|null\|undefined`   |         | Set the position target as follows:<br />- HTMLElement if overlay is position next to the HTML element<br />- String containing `top`, `right`, `left`, `bottom`, `center` combinations to position against the screen.<br />For instance: `top left` - put the overlay at `top left` point of the screen; `bottom` - put overlay at `bottom center` point of the screen |
| `positionTargetConfig (readonly)` |                              | `PositionTargetStrategy`            |         | Get position target configuration based on positionTarget and fullScreen properties<br />Used for caching and calculations |
| `spacing`                         | `spacing`                    | `boolean`                           | false   | True to apply spacing for overlay content        |
| `transitionStyle`                 | `transition-style`           | `TransitionStyle\|null\|undefined`  |         | Set the transition style                         |
| `transitioning (readonly)`        |                              | `boolean`                           | false   | Returns true if overlay is doing opening or closing transition |
| `transparent`                     | `transparent`                | `boolean`                           | false   | True to make overlay background transparent      |
| `verticalOffset`                  | `vertical-offset`            | `number`                            | 0       | A pixel value that will be added to the position calculated on the vertical axis.<br />The offset will be applied either to the `top` or `bottom` depending on the `positionTarget` |
| `withBackdrop`                    | `with-backdrop`              | `boolean`                           | false   | True to show backdrop                            |
| `withShadow`                      | `with-shadow`                | `boolean`                           | false   | True to add shadow                               |
| `x`                               | `x`                          | `number\|null\|undefined`           |         | Set a specific x coordinate                      |
| `y`                               | `y`                          | `number\|null\|undefined`           |         | Set a specific y coordinate                      |
| `zIndex`                          | `z-index`                    | `number\|null\|undefined`           |         | Set a preferable z-index to override automatically calculated z-index |

## Methods

| Method        | Type       | Description                                      |
|---------------|------------|--------------------------------------------------|
| `clearCached` | `(): void` | Clear all cached values.<br />Run when external changes occur to styles to re-calculate position. |
| `fit`         | `(): void` | Fit the overlay panel                            |
| `refit`       | `(): void` | Clear all cached values and fit the overlay.<br />Use this function if any of `maxWidth`, `maxHeight`, `minWidth`, `minHeight`, `height` or `width` changed |
| `toFront`     | `(): void` | Move overlay to front of other overlays          |

## Events

| Event            | Description                                      |
|------------------|--------------------------------------------------|
| `closed`         | Fired when overlay becomes invisible and close animation finished |
| `opened`         | Fired when overlay becomes visible and the open animation finished |
| `opened-changed` | Fired when the user changes open state of overlay e.g. when the user presses escape key or uses close button to close the overlay. The event is not triggered if `opened` property is changed programmatically. |
| `refit`          | Fired when refit algorithm finishes calculations |