• Public
  • Public/Protected
  • All

Class ModalRequest

Allows a client to make a request to a poppy service


  • ModalRequest




launcher?: string | ((popup: Window, request: ModalRequest) => void)

URL or JavaScript function to use as a launcher if no service is specified.

A launcher allows the user to specify a service to use by some means. A default implementation is provided with the "Injected" module.

overlay?: string | HTMLElement | ((request: ModalRequest) => () => void)

Modal overlay to show while the popup is open

This may be a hidden DOM node or a string with a CSS selector for a hidden DOM node - when it's time to display it its display CSS property will be set to "block", and then when it's time to hide it it'll be set to "display: none". Clicking on the node will cause the request to be cancelled.

May also be a function that is called when the overlay should be displayed with a single parameter, the current request. The function must return another function which will be called when it's time to close the overlay.

service?: string

The URL of the service page to open in the popup. Optional, but a launcher must be set if not specified. (May also be specified as the parameter to the constructor)

container?: Element

The DOM node under which to insert request-related elements, in particular the proxy iframe. Instead of setting this property directly, consider using the prepareProxy() method which also prepares an initial proxy iframe to work around some popup blockers (in particular Chrome on Android).

current?: ModalRequest

The currently open request, if any

ieHack?: string

Optional hack to allow older IE versions to work.

IE 10 and older builds of IE 11 (newer builds don't seem to have this problem) would not allow cross-document messages to be sent between popup windows on different domains.

A workaround was identified in this Stack Overflow answer where you first open a page on the same origin, and somehow that makes it work: https://stackoverflow.com/a/36630058

(The answer uses "/" but it seems any page on the same origin will do)

nextProxy?: HTMLIFrameElement

Prepared proxy iframe for the next request

Some popup blockers (in particular Chrome on Android and UC Browser) don't seem to like it when we create the proxy iframe window at the same time as opening the popup window. To work around this, we can create the iframes ahead of time; we keep track of the next iframe here.

To create the very first iframe, use the ModalRequest.prepareProxy() method.

sandbox?: string

The sandbox value to use for the proxy iframe, if not specified will be created with "allow-scripts allow-same-origin allow-forms allow-popups allow-pointer-lock"

useInlineScriptHack?: null | boolean

Hack to allow working within sandboxed iframes (may conflict with CSP)

To prevent the popup from changing the location of the client page that opens it, it's opened using through sandboxed proxy iframe without the "allow-top-navigation" permission. Problems may arise if the client page is itself in a sandboxed iframe (for instance on JSBin or other similar services) which somehow makes it so the parent page can no longer close the popup.

The problem seems to be related to the fact that the code is not really part of the iframe's content window, the true parent of the popup. So as a workaround, we can inject JavaScript in a script tag directly into the proxy iframe making it unambiguously the popup's opener. This is not ideal and may not work depending on the server's Content Security Policy, so the default behavior if not specified is to only attempt the hack if we detect we are in a frame - but it may be disabled entirely by setting this to false.


  • get closing(): Promise<void>
  • Promise that resolves when the request is closed. Note this promise does not resolve if open() is never invoked.

    Returns Promise<void>

  • get state(): "created" | "open" | "complete"
  • The current state of the request. Starts 'created' before open is called, 'open' from when the popup is opened, and then 'complete' once the popup is closed

    Returns "created" | "open" | "complete"


  • cancel(rejectWith?: any): void
  • Cancel this request.

    This closes the poppy immediately. If open() is in progress, then any running MatchHandler will be allowed to complete normally unless a rejectWith value is specified, in which case the open() promise will be rejected regardless of the state of the Match.


    • Optional rejectWith: any

    Returns void

  • prepareProxy(container?: string | HTMLElement): void
  • Set the (optional) container property and also create an initial proxy iframe for the first request. This is optional but recommended as some popup blockers may prevent the popup from showing when we create the iframe at the same time as opening the window.


    • Optional container: string | HTMLElement

      Optional container to use as the parent for request-related DOM nodes (in particular the proxy iframe)

    Returns void

Generated using TypeDoc