Portals #1032

eric-burel · 2024-09-30T07:57:17Z

eric-burel
Sep 30, 2024

Summary

In addition to slots that work on parent-children relationship, introduce a concept of portals that works from any-level of nesting.

Background & Motivation

The component hierarchy is directly tied to the DOM hierarchy which is not always the best structure for implementing a specific feature.

I am currently thinking of 2 use cases though some more might emerge during discussions:

triggering dialogs: floating elements tend to have a specific location very high in the DOM to avoid being parasited by intermediate elements positioning logic, that's typically how you implement absolutely positioned dialogs with a guarantee that the position is computed based on the viewport and not some random parent element that used a CSS filter.
feeding the section with metadata: for this use case, we might want to run further investigation to understand the impact of not having a meta tag into the <head> section. It's certainly not clean, but I suspect it does have an impact on SEO too.

For the first use case, at the moment you may use portals from your favorite client-side library, maybe this would just need some documentation to tell whether portals are supported or not.

However for proper SEO you may want the injection into the head tag to happen during server-side rendering only, it would be ideal to support this directly in Astro.

I've encountered the second use case while working on improving TutorialKit metadata.

Multiple changes were needed to make a proper connection between .mdx files and the Layout component that renders the meta tags:

supporting a new fields in the .mdx content frontmatter
crafting a YAML friendly representation of the metadata
updating all types accordingly
updating the layout component accordingly
converting back the YAML representation into HTML

And we still only support a few metadata : image, title, description. A similar work would be needed for more advanced tags like alternate links.

Goals

Bring a portal system

Example

# lesson.mdx
title: My lesson
---
<portal to="head">
  <link rel="alternate" href="/foobar.com">
<portal />

// pages/[slug].astro
// assuming you get the content from a collection
const MarkdownContent = await lesson.render()
---
<head>
  <portal name="head />
</head>
<body>
  <!-- This component will also inject an alternate URL into the head-->
  <MarkdownContent />
</body>

Related:
stackblitz/tutorialkit#342
withastro/astro#8703
https://react.dev/reference/react-dom/createPortal

Fryuni · 2024-10-01T02:37:11Z

Fryuni
Oct 1, 2024
Maintainer

This seems completely doable from userland as an integration.

Enabling it (regardless if by an integration or built into Astro) would disable streaming responses for any page containing a portal tho, since it's contents can only be known when every component renders.

4 replies

Fryuni Oct 1, 2024
Maintainer

Implemented an integration for it: Fryuni/inox-tools#167

Works with Astro components and with UI framework components (tho I still need to add the proper types for all of them, only React and Preact so far).

Once I add the types and tests I'll publish it

eric-burel Oct 1, 2024
Author

@Fryuni thanks for the reply, your code was super insightful!
My takeaways:

You are implementing the portals in user-land by working on the rendered HTML, as a post-processing step. I deplore the lack of a similar feature in Next.js, which I would call an "endware", because it unlocks so many user-land tweaks like this. It's also a possible approach for injecting polyfills depending on the user agent while keeping a page dynamic.
It works server-side as expected, Astro middlewares run at build-time only for static pages so it's also static-friendly.
A downside might be the cost, you need to parse the whole HTML content to find the portal. Ideally, this should be done against a kind of Astro AST representations earlier in the rendering process, eg when rendering a complete page.
I've learnt that portal is an existing, experimental but unused valid HTML element
You said "Astro compiler remove unknown head elements" => isn't that a strange behaviour? Or is it expected to have valid HTML?

Fryuni Oct 1, 2024
Maintainer

A downside might be the cost, you need to parse the whole HTML content to find the portal. Ideally, this should be done against a kind of Astro AST representations earlier in the rendering process

Astro doesn't have such a representation. Components render directly to HTML by turning the code into a template with interpolation. You can see it happening here. The template uses a $$render tag that returns an async iterator over each part of the template string and the interpolated values.

Another thing present in that example is that Astro adds ${$$renderHead($$result)} to the interpolation. That is where any component used can statically add elements to the head powered by the compiler. This is how <script> and <style> tags from all components in the page get added to the head. But since this happens before the components in the <body> are even called it only knows about what was discovered statically (this limitation is also why a component style will be present on the page even if you don't use it but import it, which has been reported multiple times).

It brings the performance of skipping any intermediate representation but, at the same time, limits what can be done in post-processing without parsing the HTML.

I've learnt that portal is an existing, experimental but unused valid HTML element

Yes, I also found that out. Technically, any tag without a - is reserved by the HTML spec for future use. That is why custom elements for web components must have a -.

This is not really a problem here. Astro already overrides the semantics of <slot>, <script> and <style>. You have to opt-out of the Astro semantics back into the HTML semantics by adding is:inline. The same could be done for <portal> if we wanted.

You said "Astro compiler remove unknown head elements" => isn't that a strange behaviour? Or is it expected to have valid HTML?

I think it is a bug. But it was 2 a.m., so I just figured out what was happening and not why it was happening.

It does other weird things things as well. If you have a tag that is not supposed to be on the <head> inline there it doesn't emit the <body> tag

eric-burel Oct 1, 2024
Author

Another thing present in that example is that Astro adds ${$$renderHead($$result)} to the interpolation.

Interesting, maybe we could figure a solution specific to the element, because that's a significant use case. Many framework choose to have a specific solution for metadata, eg Next.js metadata export, packages like Helmet etc.

Thanks again for your detailed technical insights

zemd · 2025-04-16T13:57:20Z

zemd
Apr 16, 2025

Are there any new thoughts about this functionality? I was thinking about not adding React-portal functionality since Portals in React are pure client-side components and are related to the interactive content, but rather server-side global slots.

For instance, I would expect to have in the layout something like the following:

<slot global server:defer name="html:title" />

and inside any other component, I would like to use it as any other slot:

<title slot="html:title" />

Potentially, if the slot is placed at the end of the document, nothing can affect streaming, but I guess the server:defer thing also does not block streaming.

As far as I can see, there is no possible way to do this in the userland. However, I am pretty new to Astro.

2 replies

Fryuni Apr 23, 2025
Maintainer

server:defer is a directive for an Astro Component to be turned into a sub-request. It was something already doable on user-land that became much easier. The equivalent previous code would be to have the component under src/pages with export const partial = true and add a client JS to call it and insert the returned HTML in the page.

Anything without blocking streaming would only be doable on the client after the entire page has been streamed since they can affect parts of the document that came before, this would lead to flashing the original content.

Server-side portals is conceptually contradictory with streaming. Streaming is to send the information of earlier elements without them being affected by slower work on following components. Server-side portals is to have earlier elements affected by the result of following components, necessarily having to wait until after they are done otherwise there wouldn't be a result.

Besides that part, what you said is entirely doable on userland (it is so doable that I did it). Just not using slot tags, since they are reserved. I don't think this feature would be good as yet another behavior of the slot tag, so even it were to be added to Astro core (which I'm not in favor or against) I would personally be against a syntax like that. Maybe overriding the behavior of the experimental portal tag and allow reverting to the default HTML behavior with is:inline like the other tags Astro overrides would be a better syntax.

zemd Apr 24, 2025

the server:defer thing was my lack of understanding of this functionality, thanks for clarifying it.

overall, my view on this was that the compiler would defer the slot calculation until the next event loop tick or compiler iteration, assuming it works asynchronously. that could potentially give more flexibility in how the code can be compiled and streamed.

as a matter of taste, I still think extending slot functionality would look a little bit better than having another portal tag. but it is just my personal preference.

Portals #1032

Uh oh!

Uh oh!

eric-burel Sep 30, 2024

Summary

Background & Motivation

Goals

Example

Replies: 2 comments · 6 replies

Uh oh!

Fryuni Oct 1, 2024 Maintainer

Uh oh!

Fryuni Oct 1, 2024 Maintainer

Uh oh!

eric-burel Oct 1, 2024 Author

Uh oh!

Uh oh!

Fryuni Oct 1, 2024 Maintainer

Uh oh!

Uh oh!

eric-burel Oct 1, 2024 Author

Uh oh!

Uh oh!

zemd Apr 16, 2025

Uh oh!

Uh oh!

Fryuni Apr 23, 2025 Maintainer

Uh oh!

zemd Apr 24, 2025

eric-burel
Sep 30, 2024

Replies: 2 comments 6 replies

Fryuni
Oct 1, 2024
Maintainer

Fryuni Oct 1, 2024
Maintainer

eric-burel Oct 1, 2024
Author

Fryuni Oct 1, 2024
Maintainer

eric-burel Oct 1, 2024
Author

zemd
Apr 16, 2025

Fryuni Apr 23, 2025
Maintainer