HTML <portal> Tag

The <portal> tag in HTML serves as a container for embedding another HTML page. Unlike <iframe> which renders content as a separate frame, the <portal> tag is designed to enable a seamless transition to the target page by activating it. This feature facilitates a smoother and more integrated user experience, making transitions feel like they're part of the same page. It’s important to understand that the portal remains inactive until a user interaction triggers activation, moving the user to the portal's content.

Syntax

<portal src="url" referrerpolicy="value"  
        reveal="onactivate"
        csp="value" 
        nonce="value" >
        Fallback Content
</portal>

Attributes

Example

<portal src="/target-page.html">
    <p>This is fallback content. The portal will load the target page when activated.</p>
</portal>

More Examples

Basic Usage with src

<portal src="https://example.com/another-page">
  <p>This content appears if portal loading fails or before activation.</p>
</portal>

This example sets up a basic portal pointing to "https://example.com/another-page". Fallback content is shown initially and while the portal content is not loaded. When a user activates the portal (e.g. using Javascript) , this content disappears and user will be transitioned to the page at "https://example.com/another-page".

Using referrerpolicy

<portal src="/secure-page" referrerpolicy="no-referrer">
   <p>Fallback for secure page</p>
</portal>

Here the referrerpolicy is set to no-referrer, ensuring that the HTTP Referer header won't be included in the request for /secure-page. This is crucial for privacy-sensitive scenarios.

Using reveal attribute

<portal src="/hidden-page.html" reveal="onactivate">
  <p>Content will be visible once portal is activated.</p>
</portal>

The portal with reveal="onactivate" is initially not visible until activated. This provides better control over the loading and rendering process, ensuring that the portal's content does not load or render until the activation occurs.

CSP and nonce usage

<portal src="/protected-page.html" csp="default-src 'self'" nonce="random_string">
  <p>Fallback for protected content.</p>
</portal>

This example shows how to define a Content Security Policy (CSP) for the portal content and include a nonce value to protect the portal against XSS attacks. The CSP policy default-src 'self' restricts the content loading to the same origin and the nonce value is used with the CSP.

Activating Portal using JavaScript

<portal id="myPortal" src="/target-page.html">Fallback content</portal>

<button onclick="activatePortal()">Activate Portal</button>

<script>
  function activatePortal() {
    const portal = document.getElementById('myPortal');
    portal.activate();
  }
</script>

This code shows how a portal is activated using JavaScript. A button element triggers the activatePortal() function which gets a reference to the portal element and calls activate() on it. The user is then taken to the portal's page.

Browser Support

The <portal> tag is an experimental feature and is currently supported by only a few browsers.

• Chrome/Edge: Supported in recent versions.
• Firefox: Not supported yet.
• Safari: Not supported yet.

It's essential to check the current browser compatibility using platforms like "Can I Use" before implementing the <portal> tag in production environments.

Notes and Tips

• The <portal> tag is still experimental and subject to change.
• Use fallback content to gracefully handle cases where portals are not supported or fail to load.
• Ensure your target pages are optimized for the portal context; consider that the transition is intended to feel seamless.
• Implement appropriate security measures, such as using referrerpolicy, CSP and nonce attributes when dealing with portals that fetch from other origins.
• JavaScript is required to activate portals to control the transitions and UX.
• Avoid using the portal tag for simple content embedding. The best use case is for seamless page navigation and transitions.
• Because it is experimental make sure to test thoroughly for any kind of errors.
• If the support is not available in user's browser, the portal tag does nothing and the user continues to be in the same page with fallback content.