Portals API

This specification document has not yet been updated to reflect the 2020-04 updates to the explainer . We’ll fix that as soon as we can, but please be aware that there are probably contradictions, and the explainer should be taken as more authoritative for the time being.

1. Introduction

This section is non-normative.

This specification extendsto define a new kind of top-level browsing context , which can be embedded in another document, and a mechanism for replacing the contents of another top-level browsing context with the previously embedded context.

It is structured as a series of patches to HTML and other specifications, with each major section indicating where each it would be placed in the event of eventual graduation from incubation.

2. Portal browsing contexts

The following section would be added as a new sub-section of's Browsing contexts section.

Every browsing context has a portal state , which may be " none " (the default), " portal " or " orphaned ". A nested browsing context always has the" none ".

A portal browsing context is a browsing context whoseis " portal ".

The host element of aportal browsing contextis a portal element which embeds its rendered output and receives messages sent from the portal browsing context.

A portal element may only be awhile it is browsing-context connected or during the dispatch of the portalactivate event from which it was obtained using adoptPredecessor() .

The host browsing context of aportal browsing contextis its's node document 's browsing context .

The portal task source is a task source used for tasks related to the portal lifecycle and communication between aportal browsing contextand itshost browsing context.

• portal-activate-event.html (live test) (source)
• portals-host-hidden-after-activation.html (live test) (source)

In the case that structured deserialization throws, it may be useful to do something else to indicate it, rather than simply providing null data.

We need to specify how the session history of each browsing context is affected by activation, and supply non-normative text that explains how these histories are expected to be presented to the user.

<c- c1="">
 // In the successor document.
</c->
onportalactivate 
<c- o="">
 =
</c-> event 
<c- p="">
 =>
</c-> 
<c- p="">
 {
</c->
  
<c- c1="">
 // The predecessor document is adopted into a <portal> element...
</c->
  document
<c- p="">
 .
</c->body
<c- p="">
 .
</c->appendChild
<c- p="">
 (
</c->event
<c- p="">
 .
</c->adoptPredecessor
<c- p="">
 ());
</c->

<c- p="">
 });
</c->


<c- c1="">
 // In the predecessor document.
</c->
portalElement
<c- p="">
 .
</c->activate
<c- p="">
 ().
</c->then
<c- p="">
 (()
</c-> 
<c- p="">
 =>
</c-> 
<c- p="">
 {
</c->
  
<c- c1="">
 // ...and it is guaranteed to observe that change by the time the
</c->
  
<c- c1="">
 // activation promise resolves.
</c->
  console
<c- p="">
 .
</c->assert
<c- p="">
 (
</c->window
<c- p="">
 .
</c->portalHost 
<c- k="">
 instanceof
</c-> PortalHost
<c- p="">
 );
</c->

<c- p="">
 });
</c->

3. The portal element

The following section would be added as a new subsection of's Embedded content section.

A portal element allows for aportal browsing contextto be embedded in an HTML document.

• portals-rendering.html (live test) (source)

A portal element portalElement has a guest browsing context , which is theportal browsing contextwhoseis portalElement , or null if no such browsing context exists.

A portal element has a just-adopted flag , which is a boolean and is initially false. It is set during dispatch of the portalactivate event.

The src attribute gives the URL of a page that theguest browsing contextis to contain. The attribute, if present, must be a valid non-empty URL potentially surrounded by spaces .

The referrerpolicy attribute is a referrer policy attribute . Its purpose is to set thereferrer policy used whensetting the source URL of a portal element.

A portal is similar to an iframe , in that it allows another browsing context to be embedded. However, theportal browsing contexthosted by a portal is part of a separate browsing context group , and thus a separateagent. The user agent is therefore free to use a separate event loop for the browsing contexts, even if they are same origin-domain .

[<a data-link-type="extended-attribute" href="https://heycam.github.io/webidl/#Exposed" id="ref-for-Exposed">
 <c- g="">
  Exposed
 </c-></a>=
<c- n="">
 Window
</c->, <a data-link-type="extended-attribute" href="https://html.spec.whatwg.org/multipage/dom.html#htmlconstructor" id="ref-for-htmlconstructor">
 <c- g="">
  HTMLConstructor
 </c-></a>]

<c- b="">
 interface
</c-> <dfn data-dfn-type="interface" data-export="" id="htmlportalelement"><code>
  <c- g="">
   HTMLPortalElement
  </c-></code></dfn> : <a data-link-type="idl-name" href="https://html.spec.whatwg.org/multipage/dom.html#htmlelement" id="ref-for-htmlelement">
 <c- n="">
  HTMLElement
 </c-></a> {
    [<a data-link-type="extended-attribute" href="https://html.spec.whatwg.org/multipage/custom-elements.html#cereactions" id="ref-for-cereactions">
 <c- g="">
  CEReactions
 </c-></a>] 
<c- b="">
 attribute
</c-> <a data-link-type="interface" href="https://heycam.github.io/webidl/#idl-USVString" id="ref-for-idl-USVString">
 <c- b="">
  USVString
 </c-></a> <a data-link-type="attribute" data-type="USVString" href="#dom-htmlportalelement-src" id="ref-for-dom-htmlportalelement-src">
 <c- g="">
  src
 </c-></a>;
    [<a data-link-type="extended-attribute" href="https://html.spec.whatwg.org/multipage/custom-elements.html#cereactions" id="ref-for-cereactions①">
 <c- g="">
  CEReactions
 </c-></a>] 
<c- b="">
 attribute
</c-> <a data-link-type="interface" href="https://heycam.github.io/webidl/#idl-DOMString" id="ref-for-idl-DOMString">
 <c- b="">
  DOMString
 </c-></a> <a data-link-type="attribute" data-type="DOMString" href="#dom-htmlportalelement-referrerpolicy" id="ref-for-dom-htmlportalelement-referrerpolicy">
 <c- g="">
  referrerPolicy
 </c-></a>;

    [<a data-link-type="extended-attribute" href="https://heycam.github.io/webidl/#NewObject" id="ref-for-NewObject">
 <c- g="">
  NewObject
 </c-></a>] 
<c- b="">
 Promise
</c-><
<c- b="">
 void
</c->> <a data-link-type="method" href="#dom-htmlportalelement-activate" id="ref-for-dom-htmlportalelement-activate②">
 <c- g="">
  activate
 </c-></a>(
<c- b="">
 optional
</c-> <a data-link-type="idl-name" href="#dictdef-portalactivateoptions" id="ref-for-dictdef-portalactivateoptions">
 <c- n="">
  PortalActivateOptions
 </c-></a> <dfn data-dfn-for="HTMLPortalElement/activate(options), HTMLPortalElement/activate()" data-dfn-type="argument" data-export="" id="dom-htmlportalelement-activate-options-options"><code>
  <c- g="">
   options
  </c-></code><a href="#dom-htmlportalelement-activate-options-options"></a></dfn>);
    
<c- b="">
 void
</c-> <a data-link-type="method" href="#dom-htmlportalelement-postmessage" id="ref-for-dom-htmlportalelement-postmessage">
 <c- g="">
  postMessage
 </c-></a>(
<c- b="">
 any
</c-> <dfn data-dfn-for="HTMLPortalElement/postMessage(message, options), HTMLPortalElement/postMessage(message)" data-dfn-type="argument" data-export="" id="dom-htmlportalelement-postmessage-message-options-message"><code>
  <c- g="">
   message
  </c-></code><a href="#dom-htmlportalelement-postmessage-message-options-message"></a></dfn>, 
<c- b="">
 optional
</c-> <a data-link-type="idl-name" href="https://html.spec.whatwg.org/multipage/web-messaging.html#postmessageoptions" id="ref-for-postmessageoptions">
 <c- n="">
  PostMessageOptions
 </c-></a> <dfn data-dfn-for="HTMLPortalElement/postMessage(message, options), HTMLPortalElement/postMessage(message)" data-dfn-type="argument" data-export="" id="dom-htmlportalelement-postmessage-message-options-options"><code>
  <c- g="">
   options
  </c-></code><a href="#dom-htmlportalelement-postmessage-message-options-options"></a></dfn> = {});

    
<c- b="">
 attribute
</c-> <a data-link-type="idl-name" href="https://html.spec.whatwg.org/multipage/webappapis.html#eventhandler" id="ref-for-eventhandler">
 <c- n="">
  EventHandler
 </c-></a> <dfn data-dfn-for="HTMLPortalElement" data-dfn-type="attribute" data-export="" data-type="EventHandler" id="dom-htmlportalelement-onmessage"><code>
  <c- g="">
   onmessage
  </c-></code></dfn>;
    
<c- b="">
 attribute
</c-> <a data-link-type="idl-name" href="https://html.spec.whatwg.org/multipage/webappapis.html#eventhandler" id="ref-for-eventhandler①">
 <c- n="">
  EventHandler
 </c-></a> <dfn data-dfn-for="HTMLPortalElement" data-dfn-type="attribute" data-export="" data-type="EventHandler" id="dom-htmlportalelement-onmessageerror"><code>
  <c- g="">
   onmessageerror
  </c-></code></dfn>;
};


<c- b="">
 dictionary
</c-> <dfn data-dfn-type="dictionary" data-export="" id="dictdef-portalactivateoptions"><code>
  <c- g="">
   PortalActivateOptions
  </c-></code></dfn> : <a data-link-type="idl-name" href="https://html.spec.whatwg.org/multipage/web-messaging.html#postmessageoptions" id="ref-for-postmessageoptions①">
 <c- n="">
  PostMessageOptions
 </c-></a> {
    
<c- b="">
 any
</c-> <dfn data-dfn-for="PortalActivateOptions" data-dfn-type="dict-member" data-export="" data-type="any " id="dom-portalactivateoptions-data"><code>
  <c- g="">
   data
  </c-></code></dfn>;
};

The src IDL attribute must reflect the src content attribute.

The referrerPolicy IDL attribute must reflect the referrerpolicy content attribute, limited to only known values .

• portal-non-http-navigation.html (live test) (source)
• portals-cross-origin-load.sub.html (live test) (source)
• portals-referrer.html (live test) (source)
• portals-referrer-inherit-header.html (live test) (source)
• portals-referrer-inherit-meta.html (live test) (source)

Whenever a portal element element has its src attribute set, changed, or removed, run the following steps:

1. If element may have a guest browsing context, thenof element .

Whenever a portal element element becomes browsing-context connected , run the following steps:

1. If element may not have a guest browsing context, then abort these steps.

2. If element ’sguest browsing contextis not null, then abort these steps.

   This ensures that a newly portal element can be inserted into the document without navigating it.

3. of element .

Whenever a portal element element becomes browsing-context disconnected , run the following steps:

1. If element may not have a guest browsing contextand itsguest browsing contextis not null, then discard it.

It might be convenient to not immediately detach the portal element, but instead to do so in a microtask. This would allow developers to reinsert the portal element without losing its browsing context.

Whenever a portal element element is adopted , run the following steps:

1. Let guestBrowsingContext be element ’sguest browsing context.

2. If guestBrowsingContext is null, then abort these steps.

3. Discard guestBrowsingContext .

Whenever a Document object document whose browsing context is aportal browsing contextis marked as completely loaded , run the following steps as part of the queued task:

1. Let element be document ’s browsing context 's.

2. Fire an event named load at element .

• portal-onload-event.html (live test) (source)
• portals-cross-origin-load.sub.html (live test) (source)

The following events are dispatched on HTMLPortalElement objects:

The portal element exposes onmessage and onmessageerror as event handler content attributes .

• htmlportalelement-event-handler-content-attributes.html (live test) (source)

3.1. Portal hosts

Every Window has a portal host object , which is a PortalHost . It is exposed through the portalHost attribute getter at times when the window may be in aportal browsing context.

Thecan be used to communicate with thehost browsing context. Its operations throw if used while its context is not aportal browsing context(i.e. there is no host), in the event that JavaScript code has saved a reference to it. At such times, the window.portalHost getter will return null.

<c- b="">
 partial
</c-> 
<c- b="">
 interface
</c-> <a data-link-type="interface" href="https://html.spec.whatwg.org/multipage/window-object.html#window" id="ref-for-window①">
 <c- g="">
  Window
 </c-></a> {
    
<c- b="">
 readonly
</c-> 
<c- b="">
 attribute
</c-> <a data-link-type="idl-name" href="#portalhost" id="ref-for-portalhost②">
 <c- n="">
  PortalHost
 </c-></a>? <a data-link-type="attribute" data-readonly="" data-type="PortalHost?" href="#dom-window-portalhost" id="ref-for-dom-window-portalhost②">
 <c- g="">
  portalHost
 </c-></a>;
};

• portals-host-exposure.sub.html (live test) (source)
• portals-host-null.html (live test) (source)

The PortalHost interface definition is as follows:

[<a data-link-type="extended-attribute" href="https://heycam.github.io/webidl/#Exposed" id="ref-for-Exposed①">
 <c- g="">
  Exposed
 </c-></a>=
<c- n="">
 Window
</c->]

<c- b="">
 interface
</c-> <dfn data-dfn-type="interface" data-export="" id="portalhost"><code>
  <c- g="">
   PortalHost
  </c-></code></dfn> : <a data-link-type="idl-name" href="https://dom.spec.whatwg.org/#eventtarget" id="ref-for-eventtarget">
 <c- n="">
  EventTarget
 </c-></a> {
    
<c- b="">
 void
</c-> <a data-link-type="method" href="#dom-portalhost-postmessage" id="ref-for-dom-portalhost-postmessage">
 <c- g="">
  postMessage
 </c-></a>(
<c- b="">
 any
</c-> <dfn data-dfn-for="PortalHost/postMessage(message, options), PortalHost/postMessage(message)" data-dfn-type="argument" data-export="" id="dom-portalhost-postmessage-message-options-message"><code>
  <c- g="">
   message
  </c-></code><a href="#dom-portalhost-postmessage-message-options-message"></a></dfn>, 
<c- b="">
 optional
</c-> <a data-link-type="idl-name" href="https://html.spec.whatwg.org/multipage/web-messaging.html#postmessageoptions" id="ref-for-postmessageoptions②">
 <c- n="">
  PostMessageOptions
 </c-></a> <dfn data-dfn-for="PortalHost/postMessage(message, options), PortalHost/postMessage(message)" data-dfn-type="argument" data-export="" id="dom-portalhost-postmessage-message-options-options"><code>
  <c- g="">
   options
  </c-></code><a href="#dom-portalhost-postmessage-message-options-options"></a></dfn>);

    
<c- b="">
 attribute
</c-> <a data-link-type="idl-name" href="https://html.spec.whatwg.org/multipage/webappapis.html#eventhandler" id="ref-for-eventhandler②">
 <c- n="">
  EventHandler
 </c-></a> <dfn data-dfn-for="PortalHost" data-dfn-type="attribute" data-export="" data-type="EventHandler" id="dom-portalhost-onmessage"><code>
  <c- g="">
   onmessage
  </c-></code><a href="#dom-portalhost-onmessage"></a></dfn>;
    
<c- b="">
 attribute
</c-> <a data-link-type="idl-name" href="https://html.spec.whatwg.org/multipage/webappapis.html#eventhandler" id="ref-for-eventhandler③">
 <c- n="">
  EventHandler
 </c-></a> <dfn data-dfn-for="PortalHost" data-dfn-type="attribute" data-export="" data-type="EventHandler" id="dom-portalhost-onmessageerror"><code>
  <c- g="">
   onmessageerror
  </c-></code><a href="#dom-portalhost-onmessageerror"></a></dfn>;
};

• portals-host-post-message.sub.html (live test) (source)

The following events are dispatched on PortalHost objects:

3.2. The PortalActivateEvent interface

[<a data-link-type="extended-attribute" href="https://heycam.github.io/webidl/#Exposed" id="ref-for-Exposed②">
 <c- g="">
  Exposed
 </c-></a>=
<c- n="">
 Window
</c->]

<c- b="">
 interface
</c-> <dfn data-dfn-type="interface" data-export="" id="portalactivateevent"><code>
  <c- g="">
   PortalActivateEvent
  </c-></code></dfn> : <a data-link-type="idl-name" href="https://dom.spec.whatwg.org/#event" id="ref-for-event">
 <c- n="">
  Event
 </c-></a> {
    <dfn data-dfn-for="PortalActivateEvent" data-dfn-type="constructor" data-export="" data-lt="PortalActivateEvent(type, eventInitDict)|constructor(type, eventInitDict)|PortalActivateEvent(type)|constructor(type)" id="dom-portalactivateevent-portalactivateevent"><code>
  <c- g="">
   constructor
  </c-></code><a href="#dom-portalactivateevent-portalactivateevent"></a></dfn>(<a data-link-type="interface" href="https://heycam.github.io/webidl/#idl-DOMString" id="ref-for-idl-DOMString①">
 <c- b="">
  DOMString
 </c-></a> <dfn data-dfn-for="PortalActivateEvent/PortalActivateEvent(type, eventInitDict), PortalActivateEvent/constructor(type, eventInitDict), PortalActivateEvent/PortalActivateEvent(type), PortalActivateEvent/constructor(type)" data-dfn-type="argument" data-export="" id="dom-portalactivateevent-portalactivateevent-type-eventinitdict-type"><code>
  <c- g="">
   type
  </c-></code><a href="#dom-portalactivateevent-portalactivateevent-type-eventinitdict-type"></a></dfn>, 
<c- b="">
 optional
</c-> <a data-link-type="idl-name" href="#dictdef-portalactivateeventinit" id="ref-for-dictdef-portalactivateeventinit">
 <c- n="">
  PortalActivateEventInit
 </c-></a> <dfn data-dfn-for="PortalActivateEvent/PortalActivateEvent(type, eventInitDict), PortalActivateEvent/constructor(type, eventInitDict), PortalActivateEvent/PortalActivateEvent(type), PortalActivateEvent/constructor(type)" data-dfn-type="argument" data-export="" id="dom-portalactivateevent-portalactivateevent-type-eventinitdict-eventinitdict"><code>
  <c- g="">
   eventInitDict
  </c-></code><a href="#dom-portalactivateevent-portalactivateevent-type-eventinitdict-eventinitdict"></a></dfn> = {});

    
<c- b="">
 readonly
</c-> 
<c- b="">
 attribute
</c-> 
<c- b="">
 any
</c-> <dfn data-dfn-for="PortalActivateEvent" data-dfn-type="attribute" data-export="" data-readonly="" data-type="any" id="dom-portalactivateevent-data"><code>
  <c- g="">
   data
  </c-></code></dfn>;
    <a data-link-type="idl-name" href="#htmlportalelement" id="ref-for-htmlportalelement②">
 <c- n="">
  HTMLPortalElement
 </c-></a> <a data-link-type="method" href="#dom-portalactivateevent-adoptpredecessor" id="ref-for-dom-portalactivateevent-adoptpredecessor②">
 <c- g="">
  adoptPredecessor
 </c-></a>();
};


<c- b="">
 dictionary
</c-> <dfn data-dfn-type="dictionary" data-export="" id="dictdef-portalactivateeventinit"><code>
  <c- g="">
   PortalActivateEventInit
  </c-></code></dfn> : <a data-link-type="idl-name" href="https://dom.spec.whatwg.org/#dictdef-eventinit" id="ref-for-dictdef-eventinit">
 <c- n="">
  EventInit
 </c-></a> {
    
<c- b="">
 any
</c-> <dfn data-default="null" data-dfn-for="PortalActivateEventInit" data-dfn-type="dict-member" data-export="" data-type="any " id="dom-portalactivateeventinit-data"><code>
  <c- g="">
   data
  </c-></code><a href="#dom-portalactivateeventinit-data"></a></dfn> = 
<c- b="">
 null
</c->;
};

For now, there is no ports attribute on PortalActivateEvent , despite it being used for data transfer in a similar way to MessageEvent . This omission is for simplicity, and could be reconsidered if a use case is found. (See also whatwg/html#4521 for a potential expansion.)

A PortalActivateEvent has an associated predecessor browsing context , which is a top-level browsing context or null, a successor window , which is a Window , an activation promise , which is apromise, and a adopted predecessor element , which is a portal element or null.

• portal-activate-event-constructor.html (live test) (source)

4. Miscellaneous HTML updates

This section contains various small patches to miscellaneous areas of the HTML Standard.

4.1. The MessageEvent interface

The MessageEventSource union is extended to include the new interfaces which can produce MessageEvent events.

<c- b="">
 typedef
</c-> (<a data-link-type="idl-name" href="https://html.spec.whatwg.org/multipage/window-object.html#windowproxy" id="ref-for-windowproxy②">
 <c- n="">
  WindowProxy
 </c-></a> 
<c- b="">
 or
</c-> <a data-link-type="idl-name" href="https://html.spec.whatwg.org/multipage/web-messaging.html#messageport" id="ref-for-messageport②">
 <c- n="">
  MessagePort
 </c-></a> 
<c- b="">
 or
</c-> <a data-link-type="idl-name" href="https://w3c.github.io/ServiceWorker/#serviceworker" id="ref-for-serviceworker">
 <c- n="">
  ServiceWorker
 </c-></a> 
<c- b="">
 or
</c-> <a data-link-type="idl-name" href="#htmlportalelement" id="ref-for-htmlportalelement③">
 <c- n="">
  HTMLPortalElement
 </c-></a> 
<c- b="">
 or
</c-> <a data-link-type="idl-name" href="#portalhost" id="ref-for-portalhost⑤">
 <c- n="">
  PortalHost
 </c-></a>) <dfn data-dfn-type="typedef" data-export="" id="typedefdef-messageeventsource"><code>
  <c- g="">
   MessageEventSource
  </c-></code></dfn>;

4.2. Event handlers

The table of event handlers which must be supported by Window objects, as event handler IDL attributes on the Window objects themselves (i.e. the table containing onafterprint ), gets extended with the following row:

The corresponding WindowEventHandlers mixin gets extended as follows:

<c- b="">
 partial
</c-> 
<c- b="">
 interface
</c-> 
<c- b="">
 mixin
</c-> <a data-link-type="interface" href="https://html.spec.whatwg.org/multipage/webappapis.html#windoweventhandlers" id="ref-for-windoweventhandlers①">
 <c- g="">
  WindowEventHandlers
 </c-></a> {
    
<c- b="">
 attribute
</c-> <a data-link-type="idl-name" href="https://html.spec.whatwg.org/multipage/webappapis.html#eventhandler" id="ref-for-eventhandler④">
 <c- n="">
  EventHandler
 </c-></a> <dfn data-dfn-for="WindowEventHandlers" data-dfn-type="attribute" data-export="" data-type="EventHandler" id="dom-windoweventhandlers-onportalactivate"><code>
  <c- g="">
   onportalactivate
  </c-></code><a href="#dom-windoweventhandlers-onportalactivate"></a></dfn>;
};

The Events index is also updated with the following additional row:

5. Updates to other specifications

5.1. Content Security Policy

This specification integrates withas follows.

• frame-src.sub.html (live test) (source)

• frame-ancestors.sub.html (live test) (source)

activate(options) should also respect the CSPnavigate-to directive.

5.2. RFC 7034

This specification integrates with, which defines the X-Frame-Options HTTP header, as follows. Note thatalso has an open issue, whatwg/html#1230 , to define X-Frame-Options processing, and perhaps these updates would be done as part of resolving that issue.

If a browser receives content with this header field in response to a navigation request whose target browsing context is aportal browsing context, then the browser must apply the rules inas though it were to be displayed in a frame in thehost browsing contextinstead and as though the origin of the top-level browsing context topLevelBrowsingContext were the origin of the result of the following algorithm:

1. While topLevelBrowsingContext is aportal browsing context:

   1. Set topLevelBrowsingContext to itshost browsing context.

2. Return topLevelBrowsingContext .

• portals-xfo-deny.sub.html (live test) (source)

5.3. Fetch Metadata Request Headers

This specification integrates withas follows.

Sec-Fetch-Mode: nested-navigate

Per the existing processing model, the other fetch metadata headers will automatically have the same values as they would would if the load were occurring in an iframe element, with no spec updates needed.

6. Security Considerations

We should expand this section further. Much of what was formerly there is in§ 5 Updates to other specificationsnow. Once we have a more comprehensive view of all the security-related spec updates, we should summarize them in a non-normative fashion here.

6.1. Overview

This section is non-normative.

In general, aportal browsing contextshould respect policies that would apply to a nested browsing context , e.g. that would restrict whether a document can be embedded in a document from another origin .