{"id":18389566,"url":"https://github.com/anseki/plain-overlay","last_synced_at":"2025-07-02T02:03:48.241Z","repository":{"id":15901412,"uuid":"78953355","full_name":"anseki/plain-overlay","owner":"anseki","description":"The simple library for customizable overlay which covers a page, elements or iframe-windows.","archived":false,"fork":false,"pushed_at":"2025-02-22T02:43:18.000Z","size":4959,"stargazers_count":37,"open_issues_count":0,"forks_count":4,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-06-17T17:03:59.021Z","etag":null,"topics":["animation","busy","customizable","form","iframe","loading","mouse","overlay","progress","ui-widget","window"],"latest_commit_sha":null,"homepage":"https://anseki.github.io/plain-overlay/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/anseki.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-01-14T16:57:21.000Z","updated_at":"2025-06-09T10:52:33.000Z","dependencies_parsed_at":"2023-01-13T20:30:20.006Z","dependency_job_id":null,"html_url":"https://github.com/anseki/plain-overlay","commit_stats":null,"previous_names":[],"tags_count":56,"template":false,"template_full_name":null,"purl":"pkg:github/anseki/plain-overlay","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anseki%2Fplain-overlay","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anseki%2Fplain-overlay/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anseki%2Fplain-overlay/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anseki%2Fplain-overlay/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/anseki","download_url":"https://codeload.github.com/anseki/plain-overlay/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anseki%2Fplain-overlay/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263061405,"owners_count":23407606,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["animation","busy","customizable","form","iframe","loading","mouse","overlay","progress","ui-widget","window"],"created_at":"2024-11-06T01:43:45.164Z","updated_at":"2025-07-02T02:03:48.212Z","avatar_url":"https://github.com/anseki.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# PlainOverlay\n\n[![npm](https://img.shields.io/npm/v/plain-overlay.svg)](https://www.npmjs.com/package/plain-overlay) [![GitHub issues](https://img.shields.io/github/issues/anseki/plain-overlay.svg)](https://github.com/anseki/plain-overlay/issues) [![dependencies](https://img.shields.io/badge/dependencies-No%20dependency-brightgreen.svg)](package.json) [![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n\nThe simple library for customizable overlay which covers all or part of a web page.\n\n**\u003ca href=\"https://anseki.github.io/plain-overlay/\"\u003eDocument and Examples https://anseki.github.io/plain-overlay/\u003c/a\u003e**\n\n[![ss-01](ss-01.gif)](https://anseki.github.io/plain-overlay/)\n[![ss-02](ss-02.gif)](https://anseki.github.io/plain-overlay/)\n[![ss-03](ss-03.gif)](https://anseki.github.io/plain-overlay/)\n\n**Features:**\n\n- Cover all or part of a web page with an overlay.\n- Block scrolling anything under the overlay by a mouse or keys.\n- Block focusing anything under the overlay by a mouse or Tab key or access-keys.\n- Show something like a loading-animation on the overlay.\n- No dependency.\n- Single file.\n- Modern browsers are supported. (If you want to support legacy browsers such as IE 9-, see [jQuery-plainOverlay](https://anseki.github.io/jquery-plainoverlay/).)\n\nOne of the following can be specified as the target that is covered:\n\n- A current window\n- An element that has a bounding-box\n- Another window (i.e. child window such as `\u003ciframe\u003e`)\n- An element in another window\n\n## Usage\n\nLoad PlainOverlay into your web page.\n\n```html\n\u003cscript src=\"plain-overlay.min.js\"\u003e\u003c/script\u003e\n```\n\nThis is simplest case:\n\n```js\nPlainOverlay.show(); // Static method\n```\n\nNow, new overlay is shown and all of the page are covered with it.  \nYou can specify an element as the target that is covered.\n\n```js\nPlainOverlay.show(element); // element is covered\n```\n\nUse an instance method to hide the overlay.\n\n```js\nvar overlay = PlainOverlay.show();\n// Now, new overlay is shown.\n// Do something ...\noverlay.hide();\n// Now, the overlay is hidden.\n```\n\nFor options and more details, refer to the following.\n\n## Constructor\n\n```js\noverlay = new PlainOverlay([target][, options])\n```\n\nThe `target` argument is an element that will be covered with the overlay, or `window` (or `document` or `\u003chtml\u003e` or `\u003cbody\u003e`) that means all of the web page.  \nAny element that has a bounding-box is accepted. It can be an element in another window (i.e. `\u003ciframe\u003e`). `\u003ciframe\u003e` is regarded as `window` of that `\u003ciframe\u003e`.  \nThe default of `target` argument is current `window`.\n\nThe `options` argument is an Object that can have properties as [options](#options). You can also change the options by [`setOptions`](#setoptions) or [`show`](#show) methods or [properties](#properties) of the PlainOverlay instance.\n\nFor example:\n\n```js\n// Cover all of the web page, with `duration` option\nvar overlay = new PlainOverlay({duration: 400});\n```\n\n```js\n// Cover a part of the web page, with `face` option\nvar overlay = new PlainOverlay(document.getElementById('form'), {face: false});\n```\n\nSee also: [`PlainOverlay.show`](#plainoverlayshow)\n\nWhen you will do something about HTML document regardless of the PlainOverlay, you typically do that after the HTML document is ready (i.e. the HTML document has been loaded and parsed by web browser).  \nFor example:\n\n```js\n// Wait for HTML document to get ready\nwindow.addEventListener('load', function() { // NOT `DOMContentLoaded`\n  // Do something about HTML document\n  var overlay = new PlainOverlay(document.getElementById('form'));\n});\n```\n\nIf you don't wait for HTML document to be ready, you might not be able to get a target element yet, or problems with incomplete layout may occur. Also, you should do so asynchronous like the above for the performance because synchronous code blocks parsing HTML.\n\n## Methods\n\n### `show`\n\n```js\nself = overlay.show([force][, options])\n```\n\nShow the overlay.  \nIf `true` is specified for `force` argument, show it immediately without an effect. (As to the effect, see [`duration`](#options-duration) option.)  \nIf `options` argument is specified, call [`setOptions`](#setoptions) method and show the overlay. It works the same as:\n\n```js\noverlay.setOptions(options).show();\n```\n\nSee also: [`PlainOverlay.show`](#plainoverlayshow)\n\n### `hide`\n\n```js\nself = overlay.hide([force])\n```\n\nHide the overlay.  \nIf `true` is specified for `force` argument, hide it immediately without an effect. (As to the effect, see [`duration`](#options-duration) option.)\n\n### `setOptions`\n\n```js\nself = overlay.setOptions(options)\n```\n\nSet one or more options.  \nThe `options` argument is an Object that can have properties as [options](#options).\n\n### `scrollLeft`, `scrollTop`\n\n```js\ncurrentLeft = overlay.scrollLeft([newLeft[, scrollTarget]])\n```\n\n```js\ncurrentTop = overlay.scrollTop([newTop[, scrollTarget]])\n```\n\nScrolling a window or element is blocked while it is covered with the overlay. `scrollLeft` and `scrollTop` methods allow it scroll, and return current value.  \nThe value is a number of pixels that a content is scrolled to the left or upward.  \nThe default of `scrollTarget` is a `target` of the overlay.\n\n### `position`\n\n```js\nself = overlay.position()\n```\n\nUpdate the position of the overlay that covers a part of a web page.  \nIf `target` is a part of a web page, the overlay is shown at the same position as the `target`, and it is re-positioned (and resized) as needed automatically when a window that contains the `target` is resized.  \nYou should call `position` method if you moved or resized the `target` without resizing the window.\n\n## Options\n\n### \u003ca name=\"options-face\"\u003e\u003c/a\u003e`face`\n\n*Type:* Element, boolean or `undefined`  \n*Default:* `undefined` (Builtin Face)\n\nSomething that is shown on the overlay. This is usually a message or image that means \"Please wait...\".  \nIf `false` is specified, nothing is shown on the overlay.\n\nFor example, a message:\n\n```html\n\u003cdiv id=\"message\"\u003ePlease wait...\u003c/div\u003e\n```\n\n```js\nvar overlay = new PlainOverlay({face: document.getElementById('message')});\n```\n\nFor example, an image:\n\n```html\n\u003cimg id=\"image\" src=\"loading.svg\"\u003e\n```\n\n```js\nvar overlay = new PlainOverlay({face: document.getElementById('image')});\n```\n\nFor example, an inline SVG:\n\n```html\n\u003csvg id=\"svg\" version=\"1.1\"\u003e\n  \u003c!-- ... --\u003e\n\u003c/svg\u003e\n```\n\n```js\nvar overlay = new PlainOverlay({face: document.getElementById('svg')});\n```\n\n### \u003ca name=\"options-duration\"\u003e\u003c/a\u003e`duration`\n\n*Type:* number  \n*Default:* `200`\n\nA number determining how long (milliseconds) the effect (fade-in/out) animation for showing and hiding the overlay will run.\n\n### \u003ca name=\"options-blur\"\u003e\u003c/a\u003e`blur`\n\n*Type:* number or boolean  \n*Default:* `false`\n\nApplies a Gaussian blur to the `target` while the overlay is shown. Note that the current browser might not support it.  \nIt is not applied if `false` is specified.\n\nFor example:\n\n```js\noverlay.blur = 3;\n```\n\n### \u003ca name=\"options-style\"\u003e\u003c/a\u003e`style`\n\n*Type:* Object or `undefined`  \n*Default:* `undefined`\n\nAn Object that can have CSS properties that are added to the overlay.\n\nMajor properties of default style:\n\n```js\n{\n  backgroundColor: 'rgba(136, 136, 136, 0.6)',\n  cursor: 'wait',\n  zIndex: 9000\n}\n```\n\nFor example, whity overlay:\n\n```js\nvar overlay = new PlainOverlay({style: {backgroundColor: 'rgba(255, 255, 255, 0.6)'}});\n```\n\nNote that some properties that affect the layout (e.g. `width`, `border`, etc.) might not work or those might break the overlay.\n\nIf you want to change the default style (i.e. style of all overlay in the web page), you can define style rules with `.plainoverlay` class in your style-sheet.\n\nFor example, CSS rule-definition:\n\n```css\n.plainoverlay {\n  background-color: rgba(255, 255, 255, 0.6);\n}\n```\n\n### \u003ca name=\"options-onshow-onhide-onbeforeshow-onbeforehide\"\u003e\u003c/a\u003e`onShow`, `onHide`, `onBeforeShow`, `onBeforeHide`\n\n*Type:* function or `undefined`  \n*Default:* `undefined`\n\nEvent listeners:\n\n- `onBeforeShow` is called when the overlay is about to be shown. If `false` is returned, the showing is canceled.\n- `onShow` is called when a showing effect of the overlay is finished.\n- `onBeforeHide` is called when the overlay is about to be hidden. If `false` is returned, the hiding is canceled.\n- `onHide` is called when a hiding effect of the overlay is finished.\n\nIn the functions, `this` refers to the current PlainOverlay instance.\n\nFor example:\n\n```js\nvar overlay = new PlainOverlay({\n  onBeforeShow: function() {\n    if (name.value) {\n      this.face.className = 'anim'; // Start animation\n    } else {\n      alert('Please input your name');\n      return false; // Cancel the showing the overlay.\n    }\n  },\n  onHide: function() {\n    this.face.className = ''; // Stop animation\n  }\n});\n```\n\n### `onPosition`\n\n*Type:* function or `undefined`  \n*Default:* `undefined`\n\nA `position` event listener that is called when the overlay is shown (before a showing effect starts), a window that contains the `target` is resized, and [`position`](#position) method is called.  \nIn the function, `this` refers to the current PlainOverlay instance.\n\nThis is used to adjust your custom [`face`](#options-face) that depends on a layout of the overlay.\n\n## Properties\n\n### `state`\n\n*Type:* number  \n*Read-only*\n\nA number to indicate current state of the overlay.  \nIt is one of the following static constant values:\n\n- `PlainOverlay.STATE_HIDDEN` (`0`): The overlay is being hiding fully.\n- `PlainOverlay.STATE_SHOWING` (`1`): A showing effect of the overlay is running.\n- `PlainOverlay.STATE_SHOWN` (`2`): The overlay is being showing fully.\n- `PlainOverlay.STATE_HIDING` (`3`): A hiding effect of the overlay is running.\n\nFor example:\n\n```js\ntoggleButton.addEventListener('click', function() {\n  if (overlay.state === PlainOverlay.STATE_HIDDEN ||\n      overlay.state === PlainOverlay.STATE_HIDING) {\n    overlay.show();\n  } else {\n    overlay.hide();\n  }\n}, false);\n```\n\n### `style`\n\n*Type:* CSSStyleDeclaration  \n*Read-only*\n\nA CSSStyleDeclaration object of the overlay to get or set the CSS properties.\n\nFor example:\n\n```js\noverlay.style.backgroundImage = 'url(bg.png)';\n```\n\n### `blockingDisabled`\n\n*Type:* boolean  \n*Default:* `false`\n\nBy default, user operation such as scrolling, focusing and selecting text is blocked.  \nIf you want, set `true` for this property to disable this behavior.\n\n### `face`\n\nGet or set [`face`](#options-face) option.\n\nFor example, change it while the overlay is shown:\n\n```js\noverlay.show({\n  face: progressBar,\n  onShow: function() {\n    setTimeout(function() {\n      overlay.face = countDown;\n    }, 3000);\n  }\n});\n```\n\n### `duration`\n\nGet or set [`duration`](#options-duration) option.\n\n### `blur`\n\nGet or set [`blur`](#options-blur) option.\n\n### `onShow`, `onHide`, `onBeforeShow`, `onBeforeHide`, `onPosition`\n\nGet or set [`onShow`, `onHide`, `onBeforeShow`, `onBeforeHide`](#options-onshow-onhide-onbeforeshow-onbeforehide), and [`onPosition`](#onposition) options.\n\n## `PlainOverlay.show`\n\n```js\noverlay = PlainOverlay.show([target][, options])\n```\n\nThis static method is a shorthand for:\n\n```js\n(new PlainOverlay(target, options)).show()\n```\n\n## See Also\n\n- [PlainModal](https://anseki.github.io/plain-modal/) : The simple library for fully customizable modal window in a web page.\n\n---\n\nThanks for images: [arian.suresh](https://www.flickr.com/photos/137304541@N04/), [jxnblk/loading](https://github.com/jxnblk/loading/), [The Pattern Library](http://thepatternlibrary.com/), [tobiasahlin/SpinKit](https://github.com/tobiasahlin/SpinKit)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fanseki%2Fplain-overlay","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fanseki%2Fplain-overlay","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fanseki%2Fplain-overlay/lists"}