All you need to know about Portals

Ashok Vishwakarma
May 9 · 5 min read

On the web, we try to load our web pages faster and faster which we have achieved to some extent using various techniques. But when it comes to transitioning another site from one, we just lose control.

Chrome has just launched a new platform API called Portals to enable us to build beautiful transitions between these navigations from one site to another.

TL;DR: Portals are available today in Chrome Canary under the flag chrome://flags/#enable-portals

Image from

Let’s dive a little deep and understand how it works and what you can do with it.

The Proposal

Published on 25th April 2018, on WICG with an intent to provide users seamless navigation from one site to another. The idea is to enable any page to show another page as an inset with a seamless transition between inset and a navigated site by introducing a completely new HTML tag <portal> with two major goals in mind to enable a seamless navigation

  • from a page showing a portal-aware destination as an inset
  • between pages of a portal-ware website.
<portal id="myPortal" src=""></portal>

The proposal also consider the following items out of the scope

  • Specifying navigation patterns, e.g. carousel, infinite lists.
  • Specifying transitions or defining APIs related to transitions.
  • Hosting arbitrary unmodified web pages with guarantees of privacy and performance.

Click below link to read more about the proposal

Why a new HTML tag?

At the very first glance, it seems like an <iframe> but it differs from the behavior of an <iframe> in many ways, which may be confusing if it uses the same HTML tag.

There are many hidden assumptions in the browser implementation that the frame hierarchy does not change over time where the portal has an intent for content to observe a universe more similar to being a top-level browsing content from load to unload.

Portal wishes to give user agents more flexibility to isolate the host and guest browsing contexts by using a separate process, even for the same-origin domains. Which will only be possible if theDocument and WindowProxy of the guest contents, is not exposed.

Portal intended to support operations (first, foremost and activated) which does not make sense for a non-portal <iframe> as these operations need additional complexity to handle.

Using a portal attribute on iframes would also require defining the behavior in the case where the attribute is added or removed from an existing element, which may already have a browsing context. In some cases, the <iframe> element currently silently ignores such changes.

Why Portals?

We have been developing Single Page Applications (SPAs) from a long time to enable smooth and nice transitions between pages but at the same time developing a SPA is complex whereas Multipage Applications (MPAs) are easier and simple to build but user end up looking at a blank screen on each navigation.

Portals offer simplicity and easier development like an MPA with seamless transitions like a SPA.

Check out the live demo from the Chrome Dev Summit for a better understanding.

Portals are available in Chrome Canary under an experimental flag chrome://flags/#enable-portals which can be confirmed once enabled.

Image from

Get started with Portal

Create a simple Portal and embed the same into the page using below code.

const portal = document.createElement('portal');
portal.src = ''; = '...';

Add a preview link to the page

<a href="javascript:void(0);" id="previewLink">Preview Portal</a>

Add an event listener to the preview link

const previewLink = document.getElementById('previewLink');
previewLink.addEventListener('click', event => {
// to pass data to your Portal
// activate method takes an options parameter
// portal.activate({data: {someKey: 'somevalue'}});

It's simple and easy 😊

Detection of Portal feature in the browser is also very easy

if( 'HTMLPortalElement' in window ){
// If browser have Portals
const portal = document.createElement('portal');

To check out the Portals demo follow the below link, make sure you have Chrome Canary with the experimental flag for Portals enabled

  1. Enter a URL you want to preview.
  2. The page will then be embedded as a <portal> element.
  3. Click on the preview.
  4. The preview will be activated after an animation.

Portal APIs and Specification

The Portal APIs are very simple and easy to use, followings are the specifications enabled so far in the Portal implementation.

  • <portal>: The HTML element consists of the src attribute which can be used to provide the page URL which Portal opens.
  • activate: is the method is used to activate the portal, which shows a nice pop-up.
  • portalHost: is the object available in the destination window which lets you check if the page is embedded as a <portal> .
  • postMessage: is used to communicate back to the host page.
  • portalactivate: is an event that fires when <portal> is activated.
  • adoptPredecessor: is a function which can be used to retrieve the previous page as a <portal> which allow creating seamless navigation between two pages.

Checking if the page opens in a portal

if( window.portalHost ) {
// do stuff the portalHost

Send data to portalHost

// on the host page
const portal = document.getElementById('portal');
portal.postMessage({someKey: 'someValue'}, ORIGIN);
// on the portal page
window.portalHost.addEventListener('message', event => {
const data =;
// do someting with data

Receiving data send by activate method

// on the host page
portal.activate({data: {'somekey': 'somevalue'}});
// on the portal page
window.portalHost.addEventListener('portalactivate', event => {
const data =;
// do someting with data

Retrieving the predecessor

// Listen to the portalactivate event
window.addEventListener('portalactivate', evt => {
// ... and creatively use the predecessor
const portal = evt.adoptPredecessor();

Full example with some nice animations

Let me your thoughts about the Portals in the comments and don’t forget to share with your friends and claps.

Ashok Vishwakarma

Written by

@GoogleDevExpert — #WebTechnologies & @angular | #Principal #Architect at @Naukri | #Entrepreneur | #TechEnthusiast | #Speaker

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade